AlexandrAI AGENTS.md
agents-md

Personal Work Agent Recovery Agent Guide

Project-specific AGENTS.md guidance for Personal Work Agent recovery service, stale runtime repair, failed runs, operational docs, and tests.

AGENTS.md

Guidance for coding agents working on Personal Work Agent recovery behavior.

Project Overview

The recovery boundary detects and repairs local runtime state that was left inconsistent by crashes, interrupted runs, stale records, or partial sync. It supports local-first reliability by making failures inspectable and repairable instead of silently reprocessing everything.

Use this boundary when changing recovery summaries, stale run detection, case repair, runtime restart behavior, or operational recovery docs.

Project Map

  • src/workagent/services/recovery.py defines RecoverySummary and RecoveryService.
  • src/workagent/runtime/tick.py can coordinate periodic recovery-adjacent behavior.
  • src/workagent/services/agent_artifacts.py and agent_session_outbox.py provide related persisted runtime outputs.
  • docs/operations/mvp1-local-recovery.md and docs/operations/mvp2-memory-repair.md describe operational repair context.
  • tests/test_recovery.py, test_offline_restart_e2e.py, test_local_flow_e2e.py, and test_agent_artifacts.py cover recovery-adjacent behavior.

Setup Commands

bashuv run pytest tests/test_recovery.py tests/test_agent_artifacts.py -q
uv run pytest tests/test_offline_restart_e2e.py tests/test_local_flow_e2e.py -q
make lint

Change Rules For Agents

  • Make recovery summaries explicit: count repaired, skipped, failed, and unchanged records separately.
  • Do not hide data loss behind successful status.
  • Keep recovery idempotent so rerunning it is safe.
  • Add tests for crash or stale-state cases before changing repair behavior.
  • Keep operational docs updated when recovery procedures change.
  • Avoid deleting artifacts unless the behavior is explicit and tested.
  • Do not publish local runtime paths or user data in public examples.

Verification

bashuv run pytest tests/test_recovery.py tests/test_offline_restart_e2e.py -q
make lint

For broad runtime repairs, run local flow and agent artifact tests as well.

Security Notes

Recovery can inspect local artifacts and session state. Treat contents as private. Redact local roots, tokens, platform payloads, and user content from logs and public docs.

PR Checklist

  • Recovery remains idempotent.
  • Failure counts are surfaced clearly.
  • Artifacts are preserved unless deletion is explicitly tested.
  • Operational docs match the repair flow.