[jeffcrouse]

The leak

Four Python processes, each orphaned to PID 1, held test databases open for a day. They blocked recreating familiar_test (#474). They came from E2E servers stopped with pkill (SIGTERM).

Reproduced:

1. Start a server on a scratch DB and run a sync over the fixture audio.
2. SIGTERM it. The server logs a clean shutdown.
3. The library-scan pool's worker survives, re-parented to PID 1 with its Postgres connection open. The per-track analysis workers do exit.

Why:

• An idle multiprocessing pool worker waits on its task queue, and it holds a write end of that queue itself, so it never sees EOF when the parent dies. It leaves only if the pool sends it a stop message.
• The scan pool (library_sync._get_scan_executor) is a module singleton whose worker outlives each sync. BackgroundManager.shutdown never stopped it; only an atexit shutdown(wait=False) did, and the worker never received that stop.
• A crash or SIGKILL never sends a stop message at all.

Who else it affects: Familiar Server stops and restarts the Python server with SIGTERM, then SIGKILL after 15 s (ServerController.stopServer). So a Mac install probably gained an orphan holding a Postgres connection on every stop or restart after a sync. I haven't checked this on a real Familiar Server install. Docker is unaffected, because stopping a container ends every process in it.

Fix

• process_setup.exit_with_parent: a daemon thread in every pool worker calls os._exit once its parent PID changes, checking once a second. macOS has no PR_SET_PDEATHSIG. Both scan_worker_init and analysis_worker_init start it, so this holds however the server dies.
• BackgroundManager.shutdown now also stops the scan pool.

Tests

• tests/test_workers_exit_with_parent.py, run on the real scan pool and on the analysis initialiser: each takes a task, then the parent SIGKILLs itself. The worker must be gone within 10 s.
  • Against the previous code, both fail with "worker … outlived its killed parent". The test cleans up any orphan it finds.
  • On this branch, both pass in about 2.5 s.
• The original scenario: a real server, synced, then SIGTERMed. No children and no database connections remain.
• Full backend suite: 2,627 passed, 45 skipped. Ruff, mypy and the profile lint are clean.

🤖 Generated with Claude Code

https://claude.ai/code/session_01UpUascYWiPxuH2vtav72eV