Expert Queue — Item States

Reference: the four states an Expert Queue item moves through, and what each one means. Last updated: 2026-06-02 Audience: Experts, Engineering, AM, QA Surface: /workspace/queue (Expert workspace) Related: Expert Queue feature, Conversation Status Lifecycle, ADR-007 Expert Access Scope

---

TL;DR — the one question that distinguishes them

Every state answers "who is being waited on right now?"

UI label	DB value	Who's it waiting on?	Terminal?
Pending	pending	The Expert (review + reply)	No
Awaiting	awaiting_client	The client (their reply)	No
Resolved	resolved	Nobody — closed	Yes
Deferred	snoozed	Nobody for now — snoozed	No

One-liner: Pending = your turn · Awaiting = client's turn · Resolved = done · Deferred = look at it later.

---

State machine

        new escalation / client reply / defer expiry
                          │
                          ▼
                  ┌──────────────┐
                  │   Pending    │  ← waiting on Expert
                  └──────┬───────┘
            ┌────────────┼────────────┐
       Expert replies   Defer       Resolve
            │            │             │
            ▼            ▼             ▼
      ┌───────────┐ ┌──────────┐ ┌──────────┐
      │ Awaiting  │ │ Deferred │ │ Resolved │
      │  (client) │ │ (snoozed)│ │  (final) │
      └─────┬─────┘ └────┬─────┘ └──────────┘
            │            │
      client replies  defer TTL expires
        (automatic)    (cron, automatic)
            │            │
            └───►Pending◄─┘

---

1. Pending — pending

Meaning: the ball is in the Expert's court. The item is waiting for an Expert to review the AI draft and respond.

Entry triggers (three ways in):

1. A conversation is escalated into the queue (createQueueItem())
2. A client replies while the item was awaiting_client → auto-flips back to pending
3. A deferred item's timer expires → cron resurfaces it to pending

Transitions out:

• → Awaiting when the Expert sends a reply (POST /expert-queue/:id/respond)
• → Resolved when the Expert resolves it (POST /expert-queue/:id/resolve)
• → Deferred when the Expert defers it (POST /expert-queue/:id/defer)

---

2. Awaiting — awaiting_client

Meaning: the ball is in the client's court. The Expert has already replied and is waiting for the client to respond. (UI may label this "Awaiting Reply".)

Entry trigger: an Expert sends a reply via POST /expert-queue/:id/respond. The atomic claim flips the item to awaiting_client and updates the underlying conversation.

Key constraint: an Expert cannot respond again to an awaiting_client item. They must wait for the client to re-trigger it back to pending (a force=true path is planned but not implemented). This prevents double-sends.

Transitions out:

• → Pending automatically as soon as the client sends any reply
• → Resolved / Deferred via explicit Expert action

---

3. Resolved — resolved

Meaning: the conversation is closed. The Expert has taken final action; no further work is expected. This is a terminal state.

Entry trigger: an Expert explicitly resolves via POST /expert-queue/:id/resolve (or PATCH /expert-queue/:id/status). Stamps resolvedBy + resolvedAt.

Terminal guard: responding to a resolved item returns 409 Conflict — re-opening it would overwrite the resolved state and lose the audit trail. Only an admin can manually move it back via PATCH /status (rare).

Transitions out: none automatic (terminal).

---

4. Deferred — snoozed

Meaning: temporarily set aside. The Expert wants to revisit it later, so it's hidden from the active queue until the snooze timer expires.

⚠️ Naming mismatch — read this. The UI says Deferred, the action endpoint is /defer, but the DB value is snoozed. When inspecting logs or the database, snoozed == the UI's "Deferred".

Entry trigger: Expert calls POST /expert-queue/:id/defer with optional deferHours (default 24h). Sets deferredUntil and removes it from the active list.

Auto-resurfacing: a BullMQ scheduled job (snooze-resurface) periodically finds items whose deferredUntil < now() and flips them back to Pending.

Transitions out:

• → Previous status when the Expert manually reverts (POST /expert-queue/:id/revert). The status held immediately before deferral is captured in previous_status at defer time and restored exactly — a deferred awaiting_client item reverts to awaiting_client, not pending. Falls back to Pending when previous_status is null (items deferred before the column existed). This is the only manual status change the Expert workspace UI offers (#2700).
• → Pending automatically when the defer TTL expires (cron). Auto-expiry intentionally lands on Pending regardless of previous_status — after the snooze window the item resurfaces for Expert attention.

---

Manual status changes & the PATCH /status override (#2700)

The Expert workspace deliberately exposes no free-form status picker. Every transition happens through a dedicated, state-machine-validated action:

To change…	Use	Allowed from
→ Awaiting	POST /respond	Pending (automatic on Expert reply)
→ Resolved	POST /resolve or PATCH /status (status=resolved)	Pending / Awaiting
→ Deferred	POST /defer	Pending / Awaiting
Deferred → previous	POST /revert	Snoozed only

PATCH /expert-queue/:id/status validates the transition server-side: a non-admin caller may only move an item → resolved (the Resolve button). Invalid manual transitions — pending ↔ awaiting_client, anything out of resolved (terminal), or out of snoozed (use /revert) — return 409 Conflict. SuperAdmin bypasses the validation for the rare documented override (e.g. reopening a resolved item). Before #2700 the UI offered a dropdown that allowed all of these; the dropdown was removed and the server now enforces the rules regardless of client.

---

Naming reference (UI ↔ endpoint ↔ DB)

UI label	Action endpoint	DB value
Pending	(default on create)	pending
Awaiting	POST /respond	awaiting_client
Resolved	POST /resolve	resolved
Deferred	POST /defer	snoozed

---

Key endpoints

Endpoint	Effect
GET /expert-queue?status=pending|awaiting_client|resolved|snoozed|all	List by status
POST /expert-queue/:id/respond	Pending → Awaiting
POST /expert-queue/:id/resolve	Pending/Awaiting → Resolved
POST /expert-queue/:id/defer	→ Deferred (snoozed), default 24h; captures previous_status
POST /expert-queue/:id/revert	Deferred → previous status (manual un-defer); 409 if not snoozed
PATCH /expert-queue/:id/status	Validated: non-admin → resolved only; SuperAdmin override bypasses (see #2700 above)

---

Source of truth

• Entity + status column: api/src/common/entities.ts (ExpertQueueItem)
• State transitions: api/src/expert-queue/expert-queue.service.ts
• Client-reply auto-reopen: api/src/conversations/conversations.service.ts
• UI labels: frontend/src/components/ui/TicketStatusBadge.tsx, frontend/src/app/workspace/queue/