live: heartbeat sync 2026-10-20T15:15:41-07:00 (Refs #11)

agent/managed-skills/franksign-worktree-db-cred-trap/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: franksign-worktree-db-cred-trap
+description: "Diagnose franksign e2e seam 5 / health 503 db:down in a fresh worktree: setup-dev.sh minted a password that mismatches the shared franksign-db container."
+---
+
+# franksign fresh-worktree DB credential trap
+
+## Symptom
+`tests/run.sh` in a fresh franksign worktree fails seam 5 ("e2e server did not
+become healthy") while the server log says `franksign-api listening on :3100`.
+Manual probe shows the server IS up:
+
+```bash
+PORT=3100 node --env-file=.env apps/api/dist/cli.js >/tmp/manual-e2e.log 2>&1 &
+sleep 2; curl -s http://127.0.0.1:3100/health
+# -> 503 {"status":"degraded","db":"down",...}
+```
+
+Not a regression, not a :3100 port collision (check `ss -tlnp | grep 3100` to rule that out).
+
+## Root cause
+`infra/setup-dev.sh` mints a fresh `POSTGRES_PASSWORD` per checkout
+(`if [ ! -f infra/postgres.env ]`), but `franksign-db` + `franksign-pgdata`
+are shared box state owned by the main checkout
+(`~/Projects/franksign`). The new worktree's `.env` DATABASE_URL then fails
+TCP auth against the initialized volume.
+
+The setup script masks it: its readiness gate is
+`podman exec franksign-db pg_isready`, which uses the in-container local
+socket and passes regardless of password — so setup prints "postgres ready"
+while the checkout is dead on arrival.
+
+## Fix (git-ignored files, no commit needed)
+Copy the shared credentials from the owning checkout:
+
+```bash
+grep DATABASE_URL /home/blank/Projects/franksign/.env   # source of truth
+# PUT that exact DATABASE_URL line into this worktree's .env
+# PUT the matching POSTGRES_PASSWORD into this worktree's infra/postgres.env
+```
+
+Gotcha: the shared password may contain literal `$$`. Keep it byte-for-byte —
+systemd `EnvironmentFile` and `node --env-file` both read values literally,
+so `$$` in the file IS `$$` in the password. No escaping, no de-escaping.
+
+## Verify
+```bash
+PORT=3100 node --env-file=.env apps/api/dist/cli.js &  # then
+curl -fsS http://127.0.0.1:3100/health   # -> {"status":"ok","db":"up"}
+tests/run.sh                             # 14/14
+```
+
+## Permanent fix (proposed, not yet landed)
+`setup-dev.sh` should reuse `~/.config/containers/systemd/postgres.env`
+(symlink to the owning checkout) when present instead of minting new creds.