fix(workspace): index the unread count so a poll doesn't scan every message (#3064)

[dolho]

Summary

• count_unread_by_session runs on every 20s Workspace poll, per open tab. Its message arm filters enterprise_portal_messages by the viewer, role = 'assistant', the thread and created_at past a read cursor, and no index led on client_email. The plan read every message in the install.
• New index: idx_portal_messages_unread ON enterprise_portal_messages(client_email, role, session_id, created_at). Equality columns come first, then the GROUP BY key, then the range column. Index-only: no query change, no behaviour change.

Dual track (Rule #9)

• db/schema.py INDEXES, for fresh installs on both engines.
• SQLite: versioned migration portal_messages_unread_index in db/migrations.py (CREATE INDEX IF NOT EXISTS, idempotent).
• PostgreSQL: Alembic 0081_portal_messages_unread_idx, down_revision = "0080_agent_skill_sets". check_alembic_heads.py reports 82 revisions and 1 head, and check_alembic_parity.py origin/dev HEAD passes.
• db/tables.py is unchanged: the portal indexes are declared in schema.py DDL, not as Index objects, matching idx_portal_messages_convo and idx_portal_messages_session.

Query plans (the live query, captured at the cursor)

SQLite

before: SCAN m USING INDEX idx_portal_messages_session
after:  SEARCH m USING COVERING INDEX idx_portal_messages_unread (client_email=? AND role=?)

PostgreSQL 16: scratch container, 120k messages, 400 viewers, 20 agents, ANALYZEd, EXPLAIN (ANALYZE, BUFFERS).

before: Seq Scan on enterprise_portal_messages m
          Rows Removed by Filter: 119859   Buffers: shared hit=2269   Execution Time: 6.451 ms
after:  Bitmap Heap Scan on enterprise_portal_messages m
          Index Cond: ((client_email = …) AND (role = 'assistant'))
          Buffers: shared hit=143          Execution Time: 0.868 ms

With a single agent in the table, PostgreSQL already used idx_portal_messages_convo (a non-leading client_email condition, so it still walks the whole index). The seq scan appears once messages span several agents, which is the production shape.

Test Plan

• tests/unit/test_3064_portal_unread_index.py (new; red before the change):
  • EXPLAINs the SQL count_unread_by_session actually sends, captured via before_cursor_execute, on a sqlite built from the real schema.py DDL, and asserts the message table is not scanned and the new index is used.
  • A negative control: drop only the new index and the same query scans again.
  • The upgrade track: the SQLite migration adds the index to an install that predates it, and running it twice is a no-op.
  • The Alembic revision carries the same DDL and a downgrade.
• 177 passed on seeds 12345 and 99999: the new file plus schema_parity, migrations, alembic_parity_guard, alembic_revision_id_length, and the unread suites ent359_portal_chat_state and ent557_unread_never_opened_chat. Unread counts are unchanged.
• pg-migrations CI runs the real alembic upgrade head.

Merge-order note: open PRs #2984, #3021 and #3035 also add an 0081_* revision on 0080_agent_skill_sets. Whichever merges second re-chains onto the live head; alembic-head-watch will flag it.

Fixes #3064

🤖 Generated with Claude Code

[obasilakis]

Validated. Index matches the count_unread_by_session predicate (seek on client_email + role, covering session_id/created_at), both migration tracks present, single Alembic head, pg-migrations green. Mutation check: reverting the fix turns 3/4 of test_3064 red (the 4th is the negative control). Merge-order note: #2984/#3021/#3035 also add 0081 on 0080 — disjoint tables, mechanical re-parent for whichever lands later.