docs: topic notes 2026-07-09 (keys-wire, ipv6, castopod, …)

2026/2026-07-09--agent-no-hang.md

@@ -0,0 +1,27 @@
+# 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`).