koopa-admin-log/2026/2026-07-09--agent-no-hang.md

Agent rule: no hanging around (Castopod session lessons)

When automating on koopa (or any remote), never leave a command without a deadline.

Required patterns

1. HTTP: always
   curl --connect-timeout 10 --max-time 120 (adjust intentionally).
2. Long jobs: wrap with
   timeout --kill-after=15s 600s <cmd>
   (image pulls, compose up, big uploads).
3. Interactive CLIs: do not pipe blindly and hope. Prefer:
   • non-interactive flags, or
   • direct SQL / API, or
   • printf 'y\n' / yes y | head with a known prompt count.
4. Poll loops: max tries + sleep; exit non-zero on give-up (print last status).
5. Background only after starting with timeout/logging; never “wait forever” on silent pull.

Castopod-specific

• shield:user activate prompts → use SQL activate (scripts/castopod/lib.sh → cp_activate_users).
• Episode create: empty transcript_file / chapters_file fail validation; location_name must be '' or a string (null crashes).
• custom_rss must be a string (empty " " / ""), not omitted → null TypeError.

Scripts

See scripts/castopod/ (lib.sh, up.sh, status.sh).