fix(gh): fix issue 58

[krokoko]

Fixes #58

• Idempotent replay semantics: POST /v1/tasks with a previously-used Idempotency-Key from the same user now returns 200 OK with the full TaskDetail and an Idempotent-Replay: true
  response header, instead of a 409 DUPLICATE_TASK error. This aligns with industry-standard idempotency behavior (Stripe, AWS).
• Security hardening: Cross-user key collisions still return 409 with a generic message (no task leakage). Incomplete/corrupt DynamoDB records fail closed with 500 INTERNAL_ERROR and
  diagnostic logging (missing_fields).
• Defensive successResponse extension: New optional extraHeaders parameter uses a safe spread order (extraHeaders first, then protected headers) so Content-Type,
  Access-Control-Allow-Origin, and X-Request-Id can never be overridden by callers.
• TTL race handling: When the IdempotencyIndex GSI matches a stale entry but the base-table item is gone (TTL/deletion race), the system logs a warning and creates a fresh task
  instead of erroring.

Test plan

• Same-user idempotent replay returns 200 + Idempotent-Replay: true header + full TaskDetail (unit + handler-level)
• Cross-user collision returns 409 with no task data leakage (unit + handler + webhook)
• Incomplete DynamoDB record returns 500 INTERNAL_ERROR (fail-closed)
• Missing user_id on stored record returns 500 (fail-closed, not false-positive match)
• GSI match with no base-table item (TTL race) creates new task and invokes orchestrator
• extraHeaders cannot override Content-Type, Access-Control-Allow-Origin, or X-Request-Id
• Webhook handler correctly forwards Idempotency-Key and returns replay/collision responses
• All 80 tests pass across 4 test suites

Area

• cdk — infrastructure, handlers, constructs
• agent — Python runtime / Docker image
• cli — bgagent client
• docs — guides or design sources (docs/guides/, docs/design/)
• tooling — root mise.toml, scripts, CI workflows

Tip: AGENTS.md lists where to edit and which tests to extend.

Related

Changes

Acknowledgment

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of the project license.