Embedded Postgres Dies On macOS Disk Pressure

When a local app or AI-agent workspace writes scheduled backups until the disk is full, embedded Postgres can die on ENOSPC and leave health checks stuck at database unreachable. The safe fix is not just more cleanup. Gate writes before backup, prune old backups first, and supervise restart with a clear failure state.

Recovery Runbook

For local apps with embedded Postgres, the recovery order should protect database state first, then reduce backup pressure, then restart the database process with bounded attempts.

1. Check free bytes before backup writes. Skip backup if the target volume is below the configured reserve.
2. Prune or rotate old backups before starting the next backup, not after a successful backup.
3. Put backup temp files on the same target volume so free-space checks match where bytes are written.
4. Supervise embedded Postgres with a bounded restart loop and a clear gave-up state.
5. Keep app support folders, databases, credentials, transcripts, and agent state review-first.

This looks like a write-before-prune failure: the scheduled backup should prove target free space and prune old backups before opening the next backup file. Once ENOSPC kills embedded Postgres, a health probe alone is not enough; the supervisor needs a bounded restart path and an explicit gave-up state.

Read-only evidence I would capture first:

df -h "$HOME" /tmp
df -i "$HOME" /tmp
du -sh "$HOME/Library/Application Support"/* 2>/dev/null | sort -h | tail -30
find "$HOME" -maxdepth 5 -type f \( -name "*.dump" -o -name "*.backup" -o -name "*.sqlite" -o -name "*.log" \) -size +500M -print0 2>/dev/null | xargs -0 du -h 2>/dev/null | sort -hr | head -40

For the fix, I would add: min-free-gb gate before backup, aggressive prune threshold before writing, temp file on the target volume, bounded Postgres restart attempts, and a health response that distinguishes disk_pressure, restarting, and gave_up.

Do Not Delete First

• Postgres data directories, write-ahead logs, or local database files without a known-good backup.
• Application Support folders that contain agent state, credentials, transcripts, or local projects.
• Current backup temp files until the backup runner has stopped.
• Agent heartbeat state before you know whether the database can be restarted cleanly.