fix(anthropic): guard credential-pool recovery check

agent/conversation_loop.py

@@ -82,6 +82,42 @@ def _ra():
     return run_agent
 
 
+def _pool_may_recover_from_rate_limit(pool, *, provider: str = "", base_url: Optional[str] = None) -> bool:
+    """Return True when credential-pool rotation may recover from a rate-limit/billing hit.
+
+    This is intentionally conservative: only suppress eager fallback when there is
+    at least one *other* credential in the pool that is not currently exhausted.
+    Single-credential pools cannot recover by rotation, so callers should continue
+    to the normal fallback path.
+    """
+    if pool is None or not getattr(pool, "has_credentials", lambda: False)():
+        return False
+
+    try:
+        from agent.credential_pool import STATUS_EXHAUSTED, _exhausted_until
+    except Exception:
+        return False
+
+    entries = list(getattr(pool, "entries", lambda: [])() or [])
+    if len(entries) <= 1:
+        return False
+
+    current = getattr(pool, "current", lambda: None)()
+    current_id = getattr(current, "id", None)
+    now = time.time()
+
+    for entry in entries:
+        if getattr(entry, "id", None) == current_id:
+            continue
+        if getattr(entry, "last_status", None) != STATUS_EXHAUSTED:
+            return True
+        exhausted_until = _exhausted_until(entry)
+        if exhausted_until is None or exhausted_until <= now:
+            return True
+
+    return False
+
+
 def run_conversation(
     agent,
     user_message: str,

docs/00_INDEX.md

@@ -0,0 +1,42 @@
+# Docs Index
+
+> Discoverability surface for repo-safe planning and coordination docs.
+
+## Active planning docs
+
+- [Account Segmentation Map](plans/2026-05-17-account-segmentation-map.md)
+  - Purpose: split testing, business, and research access.
+  - State: ready.
+- [Telegram DM User-Managed Multi-Session Topics Implementation Plan](plans/2026-05-02-telegram-dm-user-managed-multisession-topics.md)
+  - Purpose: define Telegram topic lanes.
+  - State: plan only.
+
+## Coordination / review surfaces
+
+- [Account Segmentation Handoff](control/2026-05-17_account-segmentation_handoff.md)
+  - Purpose: **Handoff** for the account split.
+- [Account Segmentation QC Checklist](qc/2026-05-17_account_segmentation_qc.md)
+  - Purpose: **QC** for the account pack.
+- [Business Account Rollout Checklist](control/2026-05-17_business-account-rollout-checklist.md)
+  - Purpose: **Checklist** for business accounts.
+- [Account Registry Template](control/2026-05-17_account-registry-template.md)
+  - Purpose: **Template** for safe fields.
+- [Account Registry Draft](control/2026-05-17_account-registry-draft.md)
+  - Purpose: **Draft** for the first set.
+- [Browser Profile Map](control/2026-05-17_browser-profile-map.md)
+  - Purpose: **Profile map**.
+- [Recovery + MFA Setup Checklist](control/2026-05-17_recovery-mfa-setup-checklist.md)
+  - Purpose: **Recovery + MFA** checklist.
+- [Account Setup Start Here](control/2026-05-17_account-setup-start-here.md)
+  - Purpose: **Front door**.
+- [Account Setup Operating Sequence](control/2026-05-17_account-setup-operating-sequence.md)
+  - Purpose: **Sequence** for setup.
+
+## Discoverability surfaces
+
+- [Docs Manifest](manifest.md)
+  - Purpose: canonical listing of the coordination docs in this repo.
+
+## Maintenance note
+
+When new coordination docs are added, update this index and the manifest together.

docs/control/2026-05-17_account-registry-draft.md

@@ -0,0 +1,111 @@
+# Account Registry Draft
+
+> Working draft for the first account set. Repo-safe only.
+
+**Support draft**
+**Decision owner:** Haz
+
+## Accounts
+
+### `qa-testing`
+
+- **Account name:** qa-testing
+- **Role:** testing / QA
+- **Purpose:** testing and demos
+- **Owner:** Haz
+- **Login identity:** to be assigned
+- **Recovery path:** to be assigned
+- **MFA method:** to be assigned
+- **Browser profile:** dedicated testing profile on the MacBook
+- **Allowed device(s):** MacBook only unless later expanded
+- **Trust level:** low
+- **Notes:** disposable
+
+### `research-m3-global`
+
+- **Account name:** research-m3-global
+- **Role:** research / high-trust
+- **Purpose:** secure research
+- **Owner:** Haz
+- **Login identity:** to be assigned
+- **Recovery path:** to be assigned
+- **MFA method:** to be assigned
+- **Browser profile:** dedicated secure research profile
+- **Allowed device(s):** MacBook only unless later expanded
+- **Trust level:** high
+- **Notes:** minimal extensions, minimal sign-ins
+
+### `recovery-admin`
+
+- **Account name:** recovery-admin
+- **Role:** recovery / backup control
+- **Purpose:** recovery and emergency access
+- **Owner:** Haz
+- **Login identity:** to be assigned
+- **Recovery path:** to be assigned
+- **MFA method:** to be assigned
+- **Browser profile:** recovery-only profile
+- **Allowed device(s):** MacBook only unless later expanded
+- **Trust level:** highest
+- **Notes:** never for daily use
+
+## Future business accounts
+
+Use this section only when a real business workflow exists.
+
+### `business-admin-<brand>`
+
+- **Account name:** business-admin-<brand>
+- **Role:** live admin / operations
+- **Purpose:** billing, settings, admin
+- **Owner:** Haz unless another explicit business owner is named
+- **Login identity:** to be assigned
+- **Recovery path:** to be assigned
+- **MFA method:** to be assigned
+- **Browser profile:** dedicated business admin profile
+- **Allowed device(s):** to be defined
+- **Trust level:** high
+- **Notes:** one per brand; avoid mixing client access
+
+### `business-support-<brand>`
+
+- **Account name:** business-support-<brand>
+- **Role:** support / day-to-day ops
+- **Purpose:** support and ops
+- **Owner:** Haz or designated ops lead
+- **Login identity:** to be assigned
+- **Recovery path:** to be assigned
+- **MFA method:** to be assigned
+- **Browser profile:** dedicated support profile
+- **Allowed device(s):** to be defined
+- **Trust level:** medium-high
+- **Notes:** keep separate from admin if possible
+
+### Optional client-facing sub-accounts
+
+- **Account name:** client/workstream-specific
+- **Role:** per-client or per-workstream access
+- **Purpose:** separate access boundary only when needed
+- **Owner:** named business owner or client lead
+- **Login identity:** to be assigned
+- **Recovery path:** to be assigned
+- **MFA method:** to be assigned
+- **Browser profile:** only if permissions alone are not enough
+- **Allowed device(s):** to be defined
+- **Trust level:** based on the workflow
+- **Notes:** do not create early
+
+## Fill-in rule
+
+If any of these are unknown, stop before the account matters:
+
+- login identity
+- recovery path
+- MFA method
+- browser profile
+- allowed device(s)
+- trust level
+
+## Safe handling rule
+
+Do not add passwords, backup codes, or any live credential material to this document.

docs/control/2026-05-17_account-registry-template.md

@@ -0,0 +1,27 @@
+# Account Registry Template
+
+> Minimum safe fields for one account.
+
+**Template**
+
+## One entry per account
+
+- **Account name:**
+- **Role:**
+- **Purpose:**
+- **Owner:**
+- **Login identity:**
+- **Recovery path:**
+- **MFA method:**
+- **Browser profile:**
+- **Allowed device(s):**
+- **Trust level:**
+- **Notes:**
+
+## Rules
+
+- Do not store passwords.
+- Do not store backup codes in this template.
+- Do not store live credentials.
+- Keep testing, business, and research entries separate.
+- If the recovery path is unknown, stop and fix that first.

docs/control/2026-05-17_account-segmentation_handoff.md

@@ -0,0 +1,40 @@
+# Account Segmentation Handoff
+
+> Keep accounts split by role.
+
+**Support handoff**
+
+**Decision:** split by role, not convenience.
+
+## What is already decided
+
+- One QA account stays the sandbox.
+- One high-trust research account stays locked down.
+- Add business accounts only with a named purpose and owner.
+- Browser/profile separation is the floor.
+- No cookie reuse. No shared passwords. MFA everywhere.
+- No VPN blocking is a fact, not the security model.
+
+## Recommended structure
+
+- `qa-testing` for messy flows.
+- `business-admin` / `business-support` for live ops.
+- `research-m3-global` for sensitive research.
+- `recovery-admin` for recovery only.
+
+## What still needs doing
+
+- Assign owners for future business accounts.
+- Record recovery before business accounts matter.
+- Choose the browser profile naming on the MacBook.
+- Decide whether any account needs extra hardening.
+
+## Discoverability surfaces
+
+- Use `docs/control/2026-05-17_account-setup-start-here.md` as the front door.
+- The index and manifest point here.
+- The QC checklist is ready.
+
+## Next safe move
+
+Create business accounts only after purpose, owner, recovery path, profile, and trust level are named.

docs/control/2026-05-17_account-setup-operating-sequence.md

@@ -0,0 +1,103 @@
+# Account Setup Operating Sequence
+
+> Safest order for the first account lanes.
+
+**Support sequence**
+**Decision owner:** Haz
+
+## Goal
+
+Create the accounts in order. No role bleed. No credential reuse. No recovery confusion.
+
+## Operating order
+
+### 1) Create the browser profiles first
+
+Create these profiles before login:
+
+- `profile-qa-testing`
+- `profile-research-secure`
+- `profile-recovery-admin`
+- `profile-business-admin-<brand>` when business rollout begins
+- `profile-business-support-<brand>` when business rollout begins
+
+Rules:
+
+- one family, one profile
+- no cross-use
+- keep secure profiles minimal
+
+### 2) Set up the recovery lane
+
+Use the recovery profile to set up recovery.
+
+Do:
+
+- assign recovery email
+- assign recovery phone if needed
+- generate backup codes
+- store backup material outside this repo
+- confirm recovery works
+
+### 3) Set up the secure research lane
+
+Use the secure profile for the high-trust account.
+
+Do:
+
+- log in only there
+- keep extensions minimal
+- keep sign-ins limited
+- confirm MFA works
+
+### 4) Set up the testing lane
+
+Use the testing profile for the messy account.
+
+Do:
+
+- create or confirm the testing account
+- keep it low-friction
+- store nothing valuable there
+- treat it as resettable
+
+### 5) Only then create business accounts
+
+Create business accounts only when each one has a real workflow.
+
+For each business account, confirm:
+
+- purpose
+- owner
+- recovery path
+- MFA method
+- browser profile
+- allowed device(s)
+- trust level
+
+If any are missing, stop.
+
+## Creation sequence for a new business account
+
+1. Name the role and brand
+2. Decide the owner
+3. Choose the browser profile
+4. Set the recovery path
+5. Enable MFA
+6. Record the safe metadata
+7. Test sign-out and recovery
+8. Confirm isolation
+
+## Pause triggers
+
+Stop and review if:
+
+- two roles share one profile
+- recovery details are unclear
+- MFA is untested
+- business accounts appear without a real workflow
+- convenience starts beating separation
+
+## Handoff
+
+When this sequence is followed, fill in the registry draft and fix any missing fields before the account matters.