fix(server): agent session scans no longer hang the server on an unreadable .git/config#23690

Problem

AgentSessionScanner.readGitIdentity read each transcript cwd's .git pointer, commondir and .git/config through the FileSystem service, on the shared 4-thread libuv pool. When open() never returns, each agentSessions.scan pins one pool thread forever, and fiber interruption cannot free it. This happens on macOS with a TCC-protected repo under ~/Documents in a headless t3 service, or anywhere with a FIFO at .git/config. After four scans every fs and DNS operation in the server queues forever. The import step spins on "Looking for projects…", /.well-known/t3/environment stops answering, and the server cannot exit.

Repro on main (ed3f965e07): run the dev server with CLAUDE_CONFIG_DIR pointing at transcripts whose cwd is a repo with mkfifo .git/config, then open the welcome wizard's Projects step four times. All four libuv-worker threads sat in wait_for_partner, and /.well-known/t3/environment timed out after 8 s while I/O-free routes still answered.

Change

On non-Windows hosts, each git file the scanner reads is now read by its own cat -- <path> child through the existing ProcessRunner, with no shell. Each read has a 2 s deadline and a 1 MiB cap. Spawning the child and reading its pipe never use the libuv pool. Only the child can block in open(), and the runner kills its process group at the deadline.

• Failed reads. A read that fails or times out yields "", the same as main's orElseSucceed(""). The directory is still listed, just without a git remote.
• Memo. A path whose own read timed out is remembered by the scanner service, so later scans don't wait on it again.
• Batching. The scan first resolves all candidate directories. It then reads pointers, commondirs and configs in three deduped phases, 16 reads at a time. A scan with blocked files waits about one deadline per phase rather than one per file.
• Unchanged. Git identity semantics are the same as main: repositories, linked worktrees, bare repos, submodule gitdir pointers and missing files.
• Windows. It keeps the in-process read, since neither TCC nor FIFOs apply there.

Scope and approval

Fixes #15971 GitCafe: https://git.cafe/pingdotgg/t3code/issues/15971 Triaged bug via the automated issue flow. Server-only change in apps/server/src/project/AgentSessionScanner.ts and its test; no contract, setting or persisted-state changes.

Verification

Focused tests in apps/server/src/project/AgentSessionScanner.test.ts: vp test run apps/server/src/project/AgentSessionScanner.test.ts gives 57/57 passed, including after merging current main. New tests, each using real FIFOs released in a finalizer:

Lint and typecheck of apps/server pass.

Runtime check with the real dev server and web wizard, on the same fixture of 6 repos with a FIFO .git/config and 1 normal repo:

Could not check: macOS with a real TCC privacy prompt. This VM is Linux, so a FIFO stands in for an open() that never returns. Unverified on macOS: whether a cat blocked on a TCC prompt dies on the runner's SIGTERM/SIGKILL. The server's pool is free either way.

Claude Opus 5.5 (implementation, tests, review) and Claude Sonnet 5.5 (review) via Claude Code in T3 Code.

🤖 Generated with Claude Code

Takeover

Round 1: no code changes; evidence and verification added below.

Round 2

4c834277b9 fixes the three round-1 findings in AgentSessionScanner.ts and its tests:

• Memo expires. A path whose read timed out is skipped for 5 minutes, then read again through the same killable cat child, so a fixed config shows its remote again without a restart. The memo holds at most 1024 paths; the oldest is evicted first.
• Deadline comment. The comment above GIT_FILE_READ_CONCURRENCY now says what the code does: each phase waits one deadline per batch of 16 blocked files (ceil(N/16)). The code is unchanged here, because one deadline per phase would need unbounded concurrent spawns.
• No wall-clock test. The concurrent-deadline test now runs on TestClock. It proves all three blocked configs are open before a single 2 s deadline passes, instead of timing the scan.
• New test: reads a once-blocked git config again after the retry interval.

The read path's timing is unchanged, so the R3/R4 runtime rows were not re-run.

Evidence

Head b2948332e2 (merge of main onto a5920956c4; the PR diff is byte-identical at both). Before = merge-base 60b35a1ee0, or ed3f965e07 for the body's runtime table. Fixture matrix (27 rows): matrix.md. Proof audit pass 2: audit2.md, SUFFICIENT.

Corrections to the description above, from the evidence:

• With more than 16 blocked files in a phase, a scan waits ceil(N/16) deadlines per phase, not one. The code comment above GIT_FILE_READ_CONCURRENCY says the same.
• The blocked-path memo is shared by every connection. It lasts for the server's lifetime and is never retried. Since round 2 an entry expires after 5 minutes, so a path that blocked once (a TCC prompt the user later grants, or a slow NFS read over 2 s) shows its remote again on the next scan after that. On main, a slow but finite read still succeeded.
• Identity is unchanged except in two cases: a .git/config whose origin sits past 1 MiB is parsed from its first 1 MiB and loses its remote, and a host without cat on PATH loses every remote.

Drivers (sha256): summary.md, drivers.sha256, scan.ts 0aa89b91…, r1.sh 4668fef1…, fixture-r1.sh a05a6b7f…, r2.sh fc37b531…, r2-probe.ts 50c84c2c…, r3r4.sh f729c68f…, r3r4-audit2.sh 64b40711…, r5.sh 95dd82d4…, fixture-r6.sh 48c1f87b…, r6.sh 33ac951c…, ws-scan.mjs 89acbafc…. Shutdown: r6-shutdown.txt.