[Step 8] Agent job claim/complete loop (cross-repo: api + agent)

[haydercyber]

Goal — REFACTOR_PLAN.md Step 8 — Cross-repo

Close the end-to-end job loop: the Control Plane creates a sync_job, the Agent claims it, executes the provider operation, and reports status. Idempotent.

Cross-repo, tracked in secrets-bridge/api. Companion issue in secrets-bridge/agent.

API side

• POST /api/v1/agent/jobs/claim — agent-authenticated; returns next runnable job for the agent's scope, marks it claimed_by=<agent_id> and claim_expires_at
• POST /api/v1/agent/jobs/{id}/complete — accepts execution result, version/hash, error if any. Idempotent on (job_id, correlation_id)
• POST /api/v1/agent/events — push status/sync events (BRD §16.1)
• Worker re-enqueues jobs whose claim expired without completion
• Claim contention handled by Redis lock (Step 6)

Agent side

• Loop: claim → execute via core/providers → complete (or error)
• Retries with backoff (BRD NFR-04)
• Never logs the secret value that flows through GetValue / PutValue (BRD §15 "Secret handling", FR-04)

Acceptance criteria

• End-to-end scenario: admin posts a job → agent claims, executes a Vault GetValue + AWS PutValue → CP shows succeeded with versions/hashes in sync_runs
• Sending the same complete twice records one result (idempotent)
• Killing the agent mid-execution → job is re-claimed after lease expiry; no double-execution thanks to idempotency key
• Failure scenarios produce typed audit events (network, auth, conflict, provider rate limit)

Hard rules (BRD)

• Idempotent execution (NFR-04)
• No secret values in DB / logs / events / errors (FR-04, §15)

References

• BRD §10.1, §12.2, §13 FR-03, FR-10, NFR-04, §16
• REFACTOR_PLAN §6 row 8

Dependencies

• Step 7 (registration + heartbeat)