BUG: Docker + SQLite (Option 4): token refresh race condition when kiro-cli is active on host

[nerdyness]

Kiro Gateway Version

2.4

What happened?

Related to #78 (:ro → :rw doc fix). After resolving that, the SQLite Docker path (Option 4) still has multiple unresolved issues.

Problem Chain

Using KIRO_CLI_DB_FILE with Docker requires fighting through several layers:

1. Read-only mount — fixed by bug(docker): kiro-cli SQLite volume mounted as read-only breaks token persistence #78
2. File permissions — kiro-cli sets data.sqlite3 to 600 (owner-only). The container's kiro user is created with useradd -r (system user, UID ≠ host UID), so it can't read or write the file. Workaround: modify the Dockerfile to create the user with UID 1000.
3. Directory permissions — SQLite needs write access to the parent directory for journal files. Host directory is 755 owned by host user. Same UID mismatch problem.
4. Token race condition — Once read/write access is solved, the gateway and kiro-cli fight over the same token. Each refresh invalidates the other's access token, causing an infinite 403 loop:

Bug Description

When the gateway and kiro-cli share the same SQLite database (mounted :rw), both processes compete to refresh tokens. Each refresh invalidates the other's access token, causing an infinite 403 loop until max retries are exhausted:

Received 403, refreshing token (attempt 1/3)
Token refreshed via AWS SSO OIDC, expires: ...
Received 403, refreshing token (attempt 2/3)
Token refreshed via AWS SSO OIDC, expires: ...
Received 403, refreshing token (attempt 3/3)
Token refreshed via AWS SSO OIDC, expires: ...
HTTP 504 - Streaming failed after 3 attempts. Unknown error.

The token refresh itself succeeds every time, but by the time the gateway uses the new token, kiro-cli has already refreshed again and invalidated it.

Steps to Reproduce

1. Log in with kiro-cli login
2. Start kiro-gateway in Docker with the recommended SQLite mount:

   volumes:
     - ~/.local/share/kiro-cli:/home/kiro/.local/share/kiro-cli
   environment:
     - KIRO_CLI_DB_FILE=/home/kiro/.local/share/kiro-cli/data.sqlite3

3. Use kiro-cli on the host while sending requests to the gateway
4. Both processes fight over the token → repeated 403s → 504

Expected Behavior

The gateway should work alongside kiro-cli without token conflicts.

Suggested Fix

Ship an entrypoint script that copies the SQLite database into the container at startup, giving the gateway its own independent token lifecycle:

#!/bin/sh
SRC="/mnt/kiro-cli-seed/data.sqlite3"
DEST="/home/kiro/.local/share/kiro-cli/data.sqlite3"
if [ -f "$SRC" ]; then
    mkdir -p "$(dirname "$DEST")"
    cp "$SRC" "$DEST"
fi
exec "$@"

With the host volume mounted read-only at a seed path:

volumes:
- ~/.local/share/kiro-cli:/mnt/kiro-cli-seed:ro

This way the gateway gets a fresh copy of credentials on each container start and manages its own refresh cycle independently.

Environment

• kiro-gateway: latest (post-bug(docker): kiro-cli SQLite volume mounted as read-only breaks token persistence #78 fix)
• Auth type: AWS SSO OIDC (Builder ID via kiro-cli)
• Deployment: Docker Compose on Linux

Debug Logs

See description above, there are several issues to fix here