feat(soft-delete): admin recovery endpoints (#834 Phase 1c)

[dolho]

Summary

Closes the user-facing side of #834. Pre-PR recovery was a direct-DB UPDATE deleted_at = NULL — unauditable, required shell access. This PR exposes the soft-deleted set + reversal via admin-only HTTP.

Stacked on #839 (which is stacked on #838). Merge order: #838 → #839 → this.

Endpoints

Method	Path	What
GET	/api/admin/soft-deleted/agents	List soft-deleted agents with deleted_at + purge_eta
POST	/api/admin/soft-deleted/agents/{name}/recover	Clear deleted_at; 404 if not in soft-deleted set
GET	/api/admin/soft-deleted/schedules[?agent_name=...]	Same for schedules; per-agent scope optional
POST	/api/admin/soft-deleted/schedules/{id}/recover	Clear schedule deleted_at

purge_eta = deleted_at + retention_days (uses agent_soft_delete_retention_days for agents = 180 default, schedule_soft_delete_retention_days for schedules = 30). Null when the corresponding retention is 0 (sweep disabled).

All four endpoints are Depends(require_admin). Every successful recovery emits a platform audit event (agent_lifecycle:recover or agent_lifecycle:schedule_recover).

Semantics

Recovery is metadata-only. For agents the container is NOT recreated automatically — operator does POST /api/agents/{name}/start if they want it running. The preserved workspace volume keeps files intact.

Live verification

1. CREATE agent + schedule, soft-delete both
2. GET soft-deleted/agents     → match, purge_eta=2026-11-10 (180d) ✓
3. GET soft-deleted/schedules  → 1 row, purge_eta=2026-06-13 (30d) ✓
4. POST recover agent          → 200, deleted_at cleared ✓
5. POST recover schedule       → 200, deleted_at cleared ✓
6. POST recover on now-live    → 404 ✓

Test plan

• 10 unit tests in tests/unit/test_admin_recovery.py: recover/list/scope, refuse-live, refuse-nonexistent, ordering, limit, agent_name filter
• Live smoke against running backend
• CI: lint + 6-seed pytest matrix + regression diff

Notes

• Draft until feat(soft-delete): agent_ownership soft-delete + retention purge (#834 Phase 1a) #838 + feat(soft-delete): agent_schedules soft-delete + retention (#834 Phase 1b) #839 land (review depends on their shape settling)
• Once feat(soft-delete): agent_ownership soft-delete + retention purge (#834 Phase 1a) #838 merges to dev, this PR's base auto-updates through the chain on rebase

Related to #834. Phase 1c (recovery surface).

🤖 Generated with Claude Code

[vybe]

This PR requires the following changes before merge:

• Move SoftDeletedAgent and SoftDeletedSchedule to models.py (Architectural Invariant #14: response models belong in models.py, not in router files)

• Update docs/memory/requirements.md with the Phase 1c recovery capability (admin recovery surface for soft-deleted agents/schedules)

• Update docs/memory/architecture.md: add the 4 new endpoints (GET/POST /api/admin/soft-deleted/agents[/{name}/recover] and GET/POST /api/admin/soft-deleted/schedules[/{id}/recover]) to the API endpoint tables

• Cap the limit query parameter on both list endpoints: limit: int = Query(200, le=500) to prevent unbounded DB reads

Please address these items and request re-review.

[dolho]

@vybe — all four blockers addressed (rebased onto the updated #839/#838 stack; new tip 21b1c8f3):

• Models centralized (Invariant Add internal health route, without which main didn't start #14) — SoftDeletedAgent / SoftDeletedSchedule moved out of routers/admin_recovery.py into models.py under a "Soft-Delete Admin Recovery (Soft-delete all entities + configurable data retention policy #834 Phase 1c)" section; router imports them and a comment points to the invariant. No other module referenced the local classes, so the move is contained.
• limit capped — both list endpoints now use limit: int = Query(200, le=500) (422 on >500), closing the unbounded-read path. Query added to the fastapi import.
• requirements.md — §32.3 expanded: all four endpoints, recovery semantics (metadata-only; container recreate is Soft-delete all entities + configurable data retention policy #834 Phase 2; operator runs POST /api/agents/{name}/start from the preserved volume), audit events, and the model-location note.
• architecture.md — new "Soft-Delete Admin Recovery (Soft-delete all entities + configurable data retention policy #834 Phase 1c)" endpoint table (method/path/auth/description for all 4) plus the recovery-semantics + model-location prose.

Stack note: --onto-rebased so #840 carries only its 2 Phase 1c commits on top of the rebased #839 (which itself sits on the #838 review-fix). No conflicts on the rebase.

Local: pytest tests/unit/test_admin_recovery.py tests/unit/test_schedule_soft_delete.py tests/unit/test_agent_soft_delete.py tests/unit/test_agent_cleanup_parity.py tests/scheduler_tests/test_database.py → 44 passed. Re-requesting review.

[vybe]

All four CHANGES_REQUESTED items from the prior review are resolved:

• SoftDeletedAgent / SoftDeletedSchedule moved to models.py (Architectural Invariant #14)
• limit: int = Query(200, le=500) cap on both list endpoints
• requirements.md §33.3 fleshed out (endpoints, recovery semantics, audit, Phase-2-deferred container recreate)
• architecture.md endpoint table added for all 4 admin recovery endpoints

Bonus: fix(recover): make recovered agents visible + honest message catches the recovery dead-end where GET /api/agents/{name} would 404 post-recover (because get_agent_by_name is Docker-backed and the container is gone) — now synthesizes a DB-backed status=stopped, needs_start=true representation, and the recover-success message honestly defers container recreate to Phase 2.

Branch was rebased onto current dev (drops the now-squashed Phase 1b ancestors). CI fully green: 6-seed pytest matrix + regression-diff + schema-parity + lint + CodeQL.