docs(agents): require multi-replica k8s correctness on every change

[buremba]

Standing rule: every change must be correct under N>1 app replicas (ClientIP affinity, per-pod in-memory SseManager/workers map). Clarifies that "No Docker/Kubernetes" applies to worker orchestration only — the app is a multi-replica k8s Deployment — and flags the API/SSE cross-pod delivery gap. Docs-only.

Extracted from the (closed) #958 worker-failure work, where an in-memory fix was caught being single-process-only.

Summary by CodeRabbit

• Documentation
  • Updated architecture guidance to reflect production deployment configurations and state management practices.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 0b1d749f-7d3d-4d7c-84f6-91a2d88cdf96

📥 Commits

Reviewing files that changed from the base of the PR and between 50dd706 and 8331622.

📒 Files selected for processing (1)

• AGENTS.md

---

📝 Walkthrough

Walkthrough

This PR updates the Orchestration section of AGENTS.md to document production multi-replica Kubernetes behavior. The guidance clarifies that pod-local in-memory state requires ClientIP affinity when multiple replicas run, cross-replica delivery must use Postgres-mediated queues, and establishes guardrails against shared in-memory state that other replicas must access or mutate.

Changes

Architecture Documentation Update

Layer / File(s)	Summary
Orchestration replica model documentation AGENTS.md	Updated Orchestration section to reflect k8s multi-replica production behavior: pod-local in-memory state under ClientIP affinity, Postgres-mediated cross-replica delivery (e.g., thread_response queue), prohibition of cross-replica shared in-memory Maps/singletons, and note of SSE/API response routing gaps.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~5 minutes

Poem

🐰 In replicas we trust, but not in shared state,
Pod-local dreams and Postgres mediate,
No cross-replica Maps to tempt our fate,
ClientIP affinity keeps us straight,
Doc wisdom: clarity comes before it's late! 📋

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Description check	❓ Inconclusive	The description addresses the PR's purpose and context, but is missing the required test plan section and validation checklist items from the template.	Add a test plan section with appropriate checkboxes (e.g., 'Docs-only, no validation required' or similar) to align with the repository template.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: adding a requirement for multi-replica Kubernetes correctness to agent-related documentation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/agents-multipod

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}