Atuin SQLite pool timeout when multiple `q` sessions share ~/.local/share/atuin/history.db

[BryanChasko]

Summary

Running multiple concurrent q (or rebrand fork kiro-cli) sessions against the same ~/.local/share/atuin/history.db reliably triggers Error: pool timed out while waiting for an open connection originating in the bundled atuin crate at crates/atuin/src/command/client.rs:334:18. The failure cascades into the user's shell prompt: starship's command-substitution-based PS1 fails to render because the atuin precmd hook is blocked, causing the literal $(/usr/local/bin/starship prompt ...) string to be printed verbatim after Ctrl+C.

Environment

• kiro-cli (Amazon Q Developer CLI fork) version: 2.2.0
• Binary build date: May 3 2026 (per filesystem mtime on installed binary)
• OS: Linux (Ubuntu, rocm-aibox), x86_64
• Shell: bash with starship prompt and atuin precmd hook
• Atuin DB path: ~/.local/share/atuin/history.db (WAL mode active)

Reproduction

1. Open three concurrent q chat (or kiro-cli chat) sessions in separate terminals — e.g. one per agent profile.
2. While all three are alive, run q login (or kiro-cli login) in a fourth terminal.
3. Either the login command itself, or the next prompt render in any of the four terminals, fails with: Error: pool timed out while waiting for an open connection and stack location crates/atuin/src/command/client.rs:334:18.

Observed Behavior

• The reporting process exits with the pool-timeout error.
• lsof ~/.local/share/atuin/history.db shows the offending q process holding two file descriptors on history.db until it exits.
• ps -ef | grep atuin returns nothing — the bundled atuin runs in-process inside the q binary, not as a daemon.
• SQLite integrity check (PRAGMA integrity_check) returns ok — no corruption, just contention.
• The history.db-wal grows large (>1MB) under load, suggesting many uncommitted transactions queued behind the writer lock.

Hypothesis (Root Cause)

The bundled atuin client opens its SQLite connection pool from each q process directly. Standalone upstream atuin (atuinsh/atuin) ships an atuin daemon process that serializes all writes through a single writer; that daemon model is what makes concurrent shells safe. The vendored copy in aws/amazon-q-developer-cli appears to skip the daemon — every q process becomes its own SQLite writer, contending for the same WAL writer lock. With N concurrent q sessions plus a q login operation that performs additional writes, the pool's acquire_timeout window is exceeded before a write slot opens.

Cascading Symptom — Starship Prompt Garbling

When the precmd hook (atuin) blocks past timeout, bash's PS1 evaluation is in an inconsistent state when the user hits Ctrl+C. The terminal then prints the literal command-substitution string from the starship init line (e.g. $(/usr/local/bin/starship prompt --terminal-width="$COLUMNS" --keymap="${KEYMAP:-}" ...)) instead of the rendered prompt. This is downstream of the atuin pool issue, not a separate starship bug — opening a fresh shell after the offending q process exits restores normal rendering immediately.

Proposed Fix Directions (for maintainer triage, not a PR yet)

1. Adopt the atuin daemon model in the bundled crate. Single writer process, all q sessions become clients. This is what upstream atuin does and what the failure mode argues for.
2. Raise the pool acquire_timeout for the bundled atuin client and add a configurable knob in q settings for users running many concurrent sessions. Lower-blast-radius change; doesn't fix the underlying contention but stops it from being a hard failure.
3. Per-session SQLite path under e.g. ~/.local/share/atuin/sessions/<pid>.db with a periodic merge into the shared history.db. Complex; likely not the right call.
4. SQLite busy_timeout pragma set aggressively (e.g. 30s) on connection open, plus retry-on-SQLITE_BUSY at the pool layer. Cheap mitigation regardless of which longer-term fix lands.

Additional Context

• This reproduces consistently on machines where users keep multiple q chat --agent <name> sessions open across different work contexts (a documented usage pattern given the agent system).
• The fork kiro-cli shares the same crates/atuin/ bundled source and exhibits identical failure.

Diagnostic Data Available

Happy to provide: raw lsof output, sqlite3 PRAGMA integrity_check + wal_checkpoint output, full bash session showing the literal-PS1 cascade, and ps snapshots of contending q processes. Indicate which would help.

---

Filed via ghost-orin-ci-cd dispatch from heraldstack-haunting; reporter is BryanChasko.