PB-044: Agent queue pruning and dead-job requeue

State: Proposed. Not approved for implementation. Priority: P2. Owner when approved: Master product (unassigned; recommend Workload management).

1. PR title and ID#

Prune finished agent jobs and add agent requeue (PB-044)

2. Business problem#

The agent's queue grows forever, and an operator can't revive a job that exhausted its retries without editing SQLite by hand.

3. Current verified behavior#

sidecar/fabric_desktop/jobqueue.py has enqueue, claim, heartbeat, finish, retry, recover, cancel, list and counts, and no delete or prune; cli.py agent has run, check, status and enqueue, no requeue. Agent tests passed in this assessment.

4. Desired behavior#

Finished (succeeded, failed, cancelled) jobs older than queue_retention_days (default 30) are removed at agent start and once a day.
fabric-desktop agent requeue <job-id> moves a dead or failed job back to queued with its attempts reset, and records who requeued it.

5. In scope and out of scope#

In scope: queue methods, CLI command, config key, tests, docs. Out of scope: multi-worker queues (PB-045), UI.

6. Architecture and files#

jobqueue.py, agent.py, agent_config.py, cli.py, deploy/agent.example.toml, sidecar/tests/test_agent.py, docs/agent.md.

7. Functional requirements#

As section 4. Requeue refuses a job that is queued or running.

8. Nonfunctional requirements#

Pruning runs in one transaction and doesn't block claims for more than a moment.

9. Dependencies#

None.

10. Security and compatibility#

Pruning deletes local queue rows only, never OneLake data. A dry-run flag on prune lists what would go and deletes nothing.

11. Acceptance criteria#

Tests: old finished jobs pruned, running and queued kept; dry run deletes nothing; requeue resets attempts; requeue of a running job refused.

12. Unit and integration tests#

As above, with the injectable clock already in JobQueue.

13. Manual verification#

Enqueue a job that fails three times, requeue it, watch it run again with agent status.

14. Documentation#

docs/agent.md queue section and the example config.

15. Rollback#

Revert; the new config key is optional.

16. Definition of Done#

Merged, tests green, FEAT-ORC-02 limitations updated after review.