disinto/docs/CLAUDE-AUTH-CONCURRENCY.md

Claude Code OAuth Concurrency Model

TL;DR

The factory runs N+1 concurrent Claude Code processes across containers that all share ~/.claude via bind mount. To avoid OAuth refresh races, they MUST be serialized by the external flock on ${HOME}/.claude/session.lock in lib/agent-sdk.sh. Claude Code's internal OAuth refresh lock does not work across containers in our mount layout. Do not remove the external flock without also fixing the lockfile placement upstream.

What we run

Container	Claude Code processes	Mount of ~/.claude
disinto-agents (persistent)	polling-loop agents via lib/agent-sdk.sh::agent_run	/home/johba/.claude → /home/agent/.claude (rw)
disinto-edge (persistent)	none directly — spawns transient containers via docker/edge/dispatcher.sh	n/a
transient containers spawned by dispatcher.sh	one-shot claude per invocation	same mount, same path

All N+1 processes can hit the OAuth refresh window concurrently when the access token nears expiry.

The race

OAuth access tokens are short-lived; refresh tokens rotate on each refresh. If two processes both POST the same refresh token to Anthropic's token endpoint simultaneously, only one wins — the other gets invalid_grant and the operator is forced to re-login.

Historically this manifested as "agents losing auth, frequent re-logins", which is the original reason lib/agent-sdk.sh introduced the external flock. The current shape (post-#606 watchdog work) is at lib/agent-sdk.sh:139,144:

local lock_file="${HOME}/.claude/session.lock"
...
output=$(cd "$run_dir" && ( flock -w 600 9 || exit 1;
  claude_run_with_watchdog claude "${args[@]}" ) 9>"$lock_file" ...)

This serializes every claude invocation across every process that shares ${HOME}/.claude/.

Why Claude Code's internal lock does not save us

src/utils/auth.ts:1491 (read from a leaked TS source — current as of April 2026) calls:

release = await lockfile.lock(claudeDir)

with no lockfilePath option. proper-lockfile defaults to creating the lock at <target>.lock as a sibling, so for claudeDir = /home/agent/.claude, the lockfile is created at /home/agent/.claude.lock.

/home/agent/.claude is bind-mounted from the host, but /home/agent/ itself is part of each container's local overlay filesystem. So each container creates its own private /home/agent/.claude.lock — they never see each other's locks. The internal cross-process lock is a no-op across our containers.

Verified empirically:

$ docker exec disinto-agents findmnt /home/agent/.claude
TARGET              SOURCE                                  FSTYPE
/home/agent/.claude /dev/loop15[/...rootfs/home/johba/.claude] btrfs

$ docker exec disinto-agents findmnt /home/agent
(blank — not a mount, container-local overlay)

$ docker exec disinto-agents touch /home/agent/test-marker
$ docker exec disinto-edge ls /home/agent/test-marker
ls: cannot access '/home/agent/test-marker': No such file or directory

(Compare with src/services/mcp/auth.ts:2097, which does it correctly by passing lockfilePath: join(claudeDir, "mcp-refresh-X.lock") — that lockfile lives inside the bind-mounted directory and IS shared. The OAuth refresh path is an upstream oversight worth filing once we have bandwidth.)

How the external flock fixes it

The lock file path ${HOME}/.claude/session.lock is inside ~/.claude/, which IS shared via the bind mount. All containers see the same inode and serialize correctly via flock. This is a sledgehammer (it serializes the entire claude -p call, not just the refresh window) but it works.

Decision matrix for new claude-using containers

When adding a new container that runs Claude Code:

1. If the container is a batch / agent context (long-running calls, tolerant of serialization): mount the same ~/.claude and route all claude calls through lib/agent-sdk.sh::agent_run so they take the external flock.

2. If the container is interactive (chat, REPL, anything where the operator is waiting on a response): do NOT join the external flock. Interactive starvation under the agent loop would be unusable — chat messages would block waiting for the current agent's claude -p call to finish, which can be minutes, and the 10-min flock -w 600 would frequently expire under a busy loop. Instead, pick one of:

   • Separate OAuth identity: new ~/.claude-chat/ on the host with its own claude auth login, mounted to the new container's /home/agent/.claude. Independent refresh state.
   • ANTHROPIC_API_KEY fallback: the codebase already supports it in docker/agents/entrypoint.sh:119-125. Different billing track but trivial config and zero coupling to the agents' OAuth.

3. Never mount the parent directory /home/agent/ instead of just .claude/ to "fix" the lockfile placement — exposes too much host state to the container.

Future fix

The right long-term fix is upstream: file an issue against Anthropic's claude-code repo asking that src/utils/auth.ts:1491 be changed to follow the pattern at src/services/mcp/auth.ts:2097 and pass an explicit lockfilePath inside claudeDir. Once that lands and we upgrade, the external flock can become a fast-path no-op or be removed entirely.

See also

• lib/agent-sdk.sh:139,144 — the external flock
• docker/agents/entrypoint.sh:119-125 — the ANTHROPIC_API_KEY fallback
• Issue #623 — chat container, auth strategy (informed by this doc)