[pacocartones]

Summary

• getDbInstance() ran PRAGMA journal_mode = WAL as the connection's first statement, before PRAGMA busy_timeout = 2000, and openSqliteDatabase() passes no driver-level timeout. A process opening the database while another one is closing its WAL connection (checkpoint + WAL delete take an EXCLUSIVE file lock for a few hundred microseconds) therefore died with database is locked (errcode 5) at src/lib/db/core.ts instead of waiting. This is the failure behind the flaky cross-process contenders never both acquire the same connection in tests/unit/exclusive-connection-leases.test.ts, which failed on release/v3.8.51 runs 33525300898 and 33493797519 and on unrelated PR runs 33571057980 and 33576326489. The busy timeout is now installed before the first statement.
• The corruption probe's isTransientProbeError matched /SQLITE_BUSY/ against error.message, but both drivers report the plain text database is locked (better-sqlite3 puts the code in .code, node:sqlite in .errcode). A transient lock during the probe therefore took the "corrupt database" path and renamed the file to storage.sqlite.probe-failed-… with Manual recovery required. The probe now recognises the drivers' real BUSY/PROTOCOL/IOERR signals (code SQLITE_BUSY|PROTOCOL|IOERR, errcode 5/10/15, or the message text) as transient.

Related Issues

• Related to feat(api): expose owner-authenticated connection display name to managed clients #11907 (exclusive connection leases; the flaky test was introduced with that feature)

Validation

• Change type: Backend (SQLite open path)
• Focused tests and category gates from the golden path: tests/unit/db-open-first-statement-busy-timeout.test.ts (new, deterministic), tests/unit/exclusive-connection-leases.test.ts (11/11, run 10 times sequentially: 10/10 green), tests/unit/probe-9541-repro.test.ts (6/6), npm run typecheck:core 0, npm run check:changelog-integrity OK
• npm run lint — repository-wide eslint exit 0 (run with --pass-on-unpruned-suppressions; the literal command reports only pre-existing unused global suppressions on this base)
• Reconciled with the current active release base release/v3.8.51; focused checks rerun afterward
• Production-code changes include a new or updated automated test in this PR
• SonarQube is temporarily opt-in while the private project has no quota; it is not a PR gate.

Mutation: with both fixes reverted the new test fails 10/10 (probe rename path); with only the probe fix it fails at core.ts getDbInstance with the identical stack CI shows; with both fixes it passes 10/10.

Tests Added Or Updated

• tests/unit/db-open-first-statement-busy-timeout.test.ts (new): seeds a real database through getDbInstance(), holds the file's EXCLUSIVE lock from a node:sqlite connection (locking_mode = EXCLUSIVE plus one read keeps it until close), spawns a child that signals readiness and then calls getDbInstance(), releases the lock 1200 ms after the signal (longer than the probe's 500 ms retry, shorter than the 2000 ms busy timeout), and asserts exit code 0, no probe-failed rename, and busy_timeout = 2000 on the opened connection.

Coverage Notes

• The reordered pragma block in src/lib/db/core.ts and the transient-error classification in src/lib/db/probeUtils.ts are both exercised by the new test; the existing lease and probe suites keep covering the surrounding behaviour.
• Not changed here, noted for a follow-up: src/lib/db/adapters/runtimeRequire.ts builds createRequire from process.argv[1] || process.cwd() without a trailing slash, so processes without argv[1] (for example node -e workers) silently fall back from better-sqlite3 to node:sqlite; and the other openSqliteDatabase() call sites in core.ts also open without a driver-level timeout.