api: separate timeout abort retries from intentional aborts

documentation/TODO__Agents.md

@@ -156,6 +156,45 @@ below. The TTL + `verify_in_flight` guards are the current mitigation.
 
 ---
 
+### [API] GET/POST retry hardening — differentiate timeout aborts vs intentional aborts
+**Status:** 🚧 Planned follow-up (2026-05-21)
+
+Recent API helper fixes restored retry/backoff for transient network `TypeError` failures.
+Current remaining gap: timeout-triggered aborts are treated the same as intentional/user
+aborts, so retries are skipped in both `api_get_object.ts` and `api_post_object.ts`.
+
+**Decision (for now):** Keep the global default timeout at **20s**.
+
+**What needs to be implemented:**
+- Separate abort reasons in GET/POST helpers:
+  - **Intentional abort** (navigation/unmount/caller cancel): fail fast, no retry
+  - **Timeout abort** (helper's own timer): eligible for retry/backoff (same class as transient network)
+- Add explicit timeout classification in code (not just `AbortError` name check), so the retry
+  loop can make a deterministic decision.
+- Keep existing capped backoff behavior (`2s -> 4s -> 6s -> 8s`) for retryable timeout/network failures.
+
+**Timeout policy improvement (class-based):**
+- Keep **20s default** as baseline.
+- Add request classes with explicit timeout selection at callsites/wrappers (not random per-page values):
+  - fast CRUD/read/search: ~20s baseline
+  - medium actions: higher bounded timeout
+  - heavy actions (uploads, exports, ffmpeg/video clip): explicit long timeout already required
+- Centralize the class mapping so timeout intent is clear and audit-friendly.
+
+**Primary files:**
+- `src/lib/ae_api/api_get_object.ts`
+- `src/lib/ae_api/api_post_object.ts`
+- Wrapper callsites in `src/lib/ae_api/` and legacy bridge points in `src/lib/api/api.ts`
+
+**Acceptance criteria:**
+- Timeout-aborted requests retry according to retry_count/backoff policy.
+- User/navigation aborts still fail fast with no retry.
+- No regression on 400/401/403/422 fail-fast handling.
+- Existing long-running flows that already set explicit timeouts (uploads/video tools/exports)
+  continue to function without behavior regressions.
+
+---
+
 ### [Launcher/VLC] Linux playback — fullscreen + pause-on-end not working
 **Status:** Mac ✅ working perfectly; Linux 🚧 deferred for later investigation
 **Date discovered:** 2026-05-20