fix(seed): mark seeded test users as email-verified

Stamps users.email_verified_at = now on insert for the four shared
test fixtures (admin/pro/teamadmin/engineer @resolutionflow.example.com),
and backfills existing rows on re-run when the column is null. Without
this, fixtures get walled by require_verified_email_after_grace once
their created_at ages past 7 days.

Re-run with: docker exec resolutionflow_backend python -m scripts.seed_test_users

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

.ai/CURRENT_TASK.md

@@ -1,22 +1,36 @@
 # CURRENT_TASK.md
 
-**Task:** Land two stacked CI PRs and lock the backend gate on `main`.
+**Active task:** None — pick next from `.ai/TODO.md` or `03-DEVELOPMENT-ROADMAP.md`.
 
-**Status:** in-progress
+## Recently shipped
 
-**Definition of Done:**
-- [ ] PR #150 (`fix/ci-workflow-config`) merged. Both `CI / backend (pull_request)` and `CI / frontend (pull_request)` show success on the merge commit.
-- [ ] PR #151 (`fix/ci-pytest-xdist`) merged. Backend CI on the merge commit completes in <6 min (was ~22 min serial).
-- [ ] `CI / backend (pull_request)` added to required status checks on `main` in Gitea branch protection (frontend is already required).
-- [ ] Optional: `CI / e2e (pull_request)` confirmed clean and added to required checks.
+- **2026-05-02 — PR #159** In-product User Guides rewrite. Merged into `main`. Replaced 15 feature-dump guides with 43 problem-oriented Diátaxis how-tos grouped under 10 categories. Dropped Maintenance Flows / AI Assistant / Flow Assist Sparkles (UI no longer exists). Renamed Step Library → Solutions Library. Authored 14 net-new how-tos for FlowPilot-era surfaces (tasklane keyboard flow, what-we-know, resolve, escalate, record-fix-outcome, post-docs-to-ticket, share-update, pause-and-leave, build-script-from-scratch, open-suggested-flow, pin-a-flow, invite-teammate, etc.). Schema additions: `category`, optional `relatedSlugs`; hub renders category sections; detail page renders related-guides footer. Fixed rendering bug where `**bold**` in `step.tip` rendered literally. Killed misleading "N sections" subtitle on guide cards. Browser-verified against engineer + owner login (sidebar labels, account sub-pages, pilot-screen header buttons, Tasks panel, integration form). Two unverified items intentionally deferred: change-teammate-role (requires non-owner test member to inspect role-change control) and detailed Resolve / Escalate modal contents (Resolve gated by 6 pending tasks in test data). tsc and Vite build clean.
+- **2026-05-01 — PR #158** Session-screen UX impeccable pass + tasklane keyboard flow. Merged into `main` as `5e10005`.
+  - **Impeccable pass** (5 sub-passes — distill / quieter / layout / typeset / polish): score 24/40 → 33/40. Removed the duplicate "Suggested checks" chip strip; added an inline `Next steps · N pending in Tasks` cue above the latest action-bearing AI bubble; consolidated the desktop session header to Resolve + Escalate + ⋯ kebab (Context / New Ticket / Update Ticket / Pause now under the kebab, mobile kebab gained Context + New Ticket parity); centered the messages column to `max-w-3xl` to match the composer; bubbles dropped to `rounded-xl`. Decoration sweep: dropped 3px side stripes (TaskLane done states, all 6 ProposalBanner modes, WhatWeKnowItem rows), gradient backgrounds (WhatWeKnow + every banner), accent borderTop on TaskLane header, backdrop-blur on handoff overlay, animate-pulse-amber ring in VerifyingBanner, bordered avatar boxes in banners. Type sweep: 14 distinct sizes → 5-step scale (10/11/12/13/14px). Icon disambiguation: `MessageCircleQuestion` split into `Pencil` (Answer CTA) + `HelpCircle` (per-check explainer). Dead `font-sans` audit (12 sites) and double `text-xs` cleanups.
+  - **TaskLane keyboard-first flow** (real feature): Enter submits + auto-advances to next pending task, Shift+Enter newline, Esc cancels, focus jumps to Send Responses after the last submission. Mouse path also auto-advances. Subtle hint row teaches the shortcut.
+  - **Banner ↔ script panel linked**: collapsing or dismissing the ProposalBanner now also hides the InlineNoTemplateDialog / TemplateMatchPanel; recording any outcome closes both surfaces.
+  - **WhatWeKnow collapsible**: per-session preference in `sessionStorage` (`rf-whatweknow-collapsed:{sessionId}`); auto-collapses on first render at ≥5 facts.
+  - **Side fix**: `ParameterizationPreview.tokenize()` word-boundary guard prevents over-eager highlighting of short values like `"D"` (no longer lights up every capital D in `Get-ADUser`).
+  - Validation: tsc clean, ESLint clean, Vite build clean. Type-check + lint passed at every commit boundary.
+- **2026-05-01 — PR #156** Suggested-fix `applied_pending` non-terminal outcome. Merged into `main` as `3ba4532`. Adds:
+  - Schema/API: `FixStatus="applied_pending"`, `pending_reason` Text column, migration `c0f3a4b7e91d`. `PATCH /suggested-fixes/{id}/outcome` accepts pending, requires notes, stamps `applied_at` only.
+  - UI: `PendingBanner` (info-tone, worked / didn't / update reason / dismiss). "Waiting to verify…" overflow option in `VerifyingBanner`. Nudge "Still checking" records pending with a reason. Page-level Resolve auto-patches pending → success before resolution flow; page-level Escalate intercepts pending the same way verifying/partial does.
+  - Generators: `resolution_note_generator` and `escalation_package_generator` system prompts handle the new status without real-looking examples.
+  - Tests: 4 new in `test_fix_outcome_endpoint.py` (21/21 suite green); prompt anti-parrot guardrail green; tsc + Vite build clean.
+  - QA report: `.gstack/qa-reports/qa-report-pending-verification-2026-04-30.md` (5/7 scripted checks PASS with concrete evidence; 2 entry-path checks deferred — same handlers verified via tested transitions).
+- **2026-04-30 — PR #155** Escalation Mode wedge merged as `ac42f97`. Senior-tech magic-moment screen. Plan: [`docs/plans/2026-04-27-escalation-mode-wedge-design.md`](../docs/plans/2026-04-27-escalation-mode-wedge-design.md).
 
-**Assumptions:**
-- The 8-core homelab Gitea Actions runner can support `-n auto` (8 xdist workers). If memory pressure shows up in CI, drop to `-n 4`.
-- pytest-cov's xdist support continues to handle the coverage merge and `--cov-fail-under=50` check correctly.
-- The per-worker DB creation in `conftest.py` is idempotent and racing workers on first import won't all try to CREATE DATABASE simultaneously — postgres serializes that, but if it surfaces issues, wrap with an advisory lock.
+## Two-metric framing (Escalation Mode — read before quoting numbers)
 
-**Out of scope:**
-- Frontend lint warnings (23 remain after #149).
-- The 23 react-hooks/exhaustive-deps warnings.
-- RLS test suite (gated behind `RUN_RLS_TESTS=1`; not in default CI).
-- Per-test transactional rollback (would shave another 30-40% off backend time but is a much bigger refactor — capture in TODO if interested).
+The in-product `GET /analytics/flowpilot/escalations` endpoint measures *post-claim time-to-first-action*. The "minutes recovered" sales claim is `manual_baseline − in_product_metric`. Manual baseline comes from the founder's stopwatch on the next 5 escalations. Don't roll the in-product number alone into "minutes recovered" — that's the apples-to-oranges miscount Codex caught.
+
+## Kill-switch (Escalation Mode)
+
+Week 8: if 0 of 3 pilots produce a verifiable hours-saved-per-week number above 1.0, revisit the wedge.
+
+## Notes for next session
+
+- Drive checks 1 (VerifyingBanner overflow → "Waiting to verify…") and 5 (nudge "Still checking" with 3+ post-apply messages) in real pilot usage to close the QA gap left by `/qa` (the tested handlers cover the same mutations, but the entry-path UI rendering wasn't exercised end-to-end).
+- Consider monitoring how often pending fixes get parked vs resolved — if engineers report losing track across sessions, revisit the cross-session "Follow-ups" dashboard rollup that was scoped out.
+- After PR #158 lands in real ticket flow, eyeball the keyboard-hint contrast and the WhatWeKnow auto-collapse-at-5 threshold — both were judgment calls (5 was a guess; the contrast bump from `/70` to full muted-foreground was based on my read, not real screen testing). Adjust if the 5-fact threshold feels too aggressive or too lenient mid-session.
+- Two follow-ups logged in `.ai/TODO.md` from the impeccable pass: `ConcludeSessionModal` paused/escalated step should allow multi-select (Ticket Notes + Client Update + Email Draft simultaneously) — real feature work; `bg-card-hover` Tailwind class doesn't resolve in `CommandPalette` — two-line fix.

.ai/DECISIONS.md

@@ -13,6 +13,113 @@
 
 ---
 
+## 2026-04-30 — Add `applied_pending` non-terminal status to suggested fixes
+
+**Context:** The verifying banner forces a synchronous verdict — worked / didn't / partial — but a lot of real MSP fixes are async. Engineer ran the script but is waiting on the client to power-cycle, AD replication, an O365 license sync. With only the existing outcomes, the engineer either leaves the banner stale (eroding the verifying signal) or guesses wrong (corrupting outcome data). User flagged the gap directly. Today's `NudgeBanner` "Still checking" button just silences the nudge — it doesn't tell the system anything.
+
+**Decision:** Add a fourth, non-terminal outcome `applied_pending`, parallel to `applied_partial`. Required `pending_reason` Text column stores the "what are you waiting on?" reason. Outcome endpoint allows pending → {success, failed, partial, dismissed} transitions; pending stamps `applied_at` but NOT `verified_at` (it's parked, not verified). Resolution-note generator frames the fix as provisional (no closure language); escalation-package generator surfaces pending verification as the leading hypothesis with a reference to what's being waited on. Frontend exposes the state via a new `PendingBanner` component (info-tone, mirrors `PartialBanner`) plus a "Waiting to verify…" overflow option in the verifying banner. `NudgeBanner` "Still checking" now records pending with a reason instead of just silencing.
+
+**Rejected:**
+
+- **Reuse `applied_partial`.** Semantically wrong — partial means "I did some of it." Pending means "I did all of it, just can't tell if it worked." Generators write different prose for each, and conflating them would lose the distinction in the customer-facing resolution note and the next-engineer escalation handoff.
+- **Add a `pending_reason` column without a new status.** The status field is what the dashboard, banner, and generators all branch on. Hiding pending state in a separate column would proliferate `IF pending_reason IS NOT NULL` checks across every consumer.
+- **Cross-session "Follow-ups" dashboard rollup in v1.** Per-session `PendingBanner` is the chat-anchored reminder. Add the dashboard surface only if engineers report losing track across multiple pending sessions in pilot use.
+- **Optional follow-up timer ("remind me in 30m").** Out of scope; nice-to-have but not the wedge.
+
+**Consequences:**
+
+- Engineers can park a fix honestly without losing the verifying signal. The state survives across sessions because it's persisted server-side.
+- `pending_reason` is preserved as audit trail when the engineer advances pending → success/failed/dismissed; it is not auto-cleared. Intentional — it tells the next reader "we waited for X, then it worked."
+- New consumers of `FixStatus` must handle the `applied_pending` case. Currently three: the banner derivation in `AssistantChatPage`, the resolution-note generator, and the escalation-package generator. All three updated in this change.
+- Migration `c0f3a4b7e91d` is reversible — downgrade rewrites pending rows back to `applied_partial` and copies `pending_reason` into `partial_notes` if the partial slot was empty, then drops the column.
+
+---
+
+## 2026-04-30 — Allow `escalated_to_id` to send chat messages in claimed sessions
+
+**Context:** During browser QA, clicking "Get AI analysis" on the magic-moment screen returned `POST /ai-sessions/{id}/chat → 400`. The senior tech who claimed the session is stored as `escalated_to_id` on `AISession`, not `user_id` (which remains the junior who created the session). `unified_chat_service.send_chat_message` queried `WHERE ai_sessions.user_id = :user_id`, so the senior's ID never matched and the endpoint rejected the request.
+
+**Decision:** Extend the ownership check in `send_chat_message` to `OR ai_sessions.escalated_to_id = :user_id` using SQLAlchemy `or_()`. This is the minimal, correct fix: the session model already has a semantically valid "also owns" field for the claiming senior; extending the WHERE clause makes that ownership real.
+
+**Rejected:**
+
+- **Transfer `user_id` to the senior on claim.** Breaks the audit trail — `user_id` is the originating engineer throughout the session lifecycle. Any query scoped to "sessions this engineer worked on" would silently lose the junior's history.
+- **A separate `can_send_message` service method.** Adds indirection with no benefit for v1. One `or_()` line in the existing query is sufficient.
+- **Checking a role/permission flag instead.** Role gating (engineer/admin) already happens at the claim endpoint. The chat-send check is about session ownership, not role. Mixing the two concerns would be confusing.
+
+**Consequences:**
+- Seniors can send AI briefings and continue chat work in sessions they have claimed. Core escalation pickup flow unblocked.
+- Any future caller of `send_chat_message` should be aware that "user_id or escalated_to_id" is the ownership rule. The service-level check is the single enforcement point.
+- `user_id` remains the originating engineer for all audit, history, and analytics queries. No data migration needed.
+
+---
+
+## 2026-04-29 — Consolidate the three per-escalation AI calls into one structured generation
+
+**Context:** A single user-initiated escalation currently triggers three separate Sonnet calls, all summarizing the same source material (session state, steps taken, "what we know") from slightly different angles:
+
+1. `_build_escalation_package_enhanced` — runs in the background `enrich_escalation_async` task, builds a rich JSON payload that's saved to `ai_session.escalation_package`.
+2. `_generate_ai_assessment` — also background, returns the magic-moment screen fields (`likely_cause`, `suggested_steps[]`, `confidence`).
+3. `generate_status_update` — engineer-triggered when they click "Ticket Notes" / "Client Update" / "Email Draft" in the conclude modal, generates audience-specific PSA prose.
+
+The user surfaced the smell: the engineer is *typically* generating a status update during the escalate flow, so the AI assessment work is being done twice with overlapping context and the engineer's PSA prose is being thrown away. Live test on 2026-04-29 also showed that bumping the assessment timeout 15s → 45s did NOT fix the empty-placeholder bug — meaning the architectural smell is also a demo blocker.
+
+**Decision:** ONE structured AI call per escalation that produces a single payload covering both the magic-moment screen's diagnostic fields AND the PSA-ready prose. Persist to `SessionHandoff`. The conclude modal's "Ticket Notes" button reads from the saved prose instead of calling the model. "Client Update" and "Email Draft" buttons trigger a cheap Haiku transformation over the saved prose (tone shift only, not a re-summarization).
+
+Proposed payload shape (final form decided during implementation):
+
+```json
+{
+  "summary_prose": "<PSA-flavored ticket-notes paragraph>",
+  "what_we_know": ["<one-liner>"],
+  "likely_cause": "<one sentence>",
+  "suggested_steps": ["<short step>"],
+  "confidence": "low | medium | high",
+  "audience_variants": {"client_update": null, "email_draft": null}
+}
+```
+
+`audience_variants` filled lazily on first user request, cached.
+
+**Rejected:**
+
+- **Just bumping the timeout further.** Already tried 5s → 15s → 45s. The architectural redundancy is the real cost — even if Sonnet completed reliably, three calls per escalation is wasteful and creates three places where state can diverge.
+- **Reusing the engineer's status update content as the AI assessment.** User's first instinct, but: status updates aren't always generated (engineer has to click), they're audience-specific (so you'd pick which one to copy), and they're prose without the structured fields the magic-moment screen needs. The right consolidation is the OTHER direction — generate ONE structured payload that the status-update buttons consume.
+- **Switching the assessment to Haiku for speed.** Faster but solves only the latency symptom, not the redundancy. Doesn't help the conclude modal's status-update buttons.
+
+**Consequences:**
+
+- Magic-moment screen populates in ~5s instead of 25s+ (work happens in the foreground escalate path, not in a background task that races with the senior's pickup).
+- Token spend per escalation drops by ~60% — one Sonnet call replaces two; the third (audience variants) becomes Haiku.
+- Engineer's "Ticket Notes" button is instant — no model round-trip.
+- Schema enforcement matters. The current `_generate_ai_assessment` returns freeform prose that the frontend stuffs into `assessment_text` because the structured fields aren't reliably parseable. The new call must use Anthropic's structured output / tool-use to enforce the schema.
+- Migration concern: `ai_session.escalation_package` JSON column has live data on existing sessions. Keep it READABLE for backward compatibility; just stop *writing* the enhanced payload from `enrich_escalation_async`. If downstream queue summaries depend on it, dual-write the basic snapshot.
+- Test fixtures (`test_handoff_manager.py`, `test_session_handoffs_api.py`) currently stub `_generate_ai_assessment` via `AsyncMock`. Updating the stubs is part of the rename.
+- The frontend SSE assessment-ready subscription (added in `0f00ee5`) stays as-is — it just listens for the new event payload.
+
+---
+
+## 2026-04-28 — Tag the task-lane state with an owner chatId
+
+**Context:** A recurring bug — every time the user returned to test escalation work, creating a new session would flash the previous session's task-lane data (questions, actions, "Tasks" pill counts) before the new session's AI response landed. The first attempt to fix it (`8914391`) added initializer-time guards (`incomingPrefill || isPickup`) that skipped the sessionStorage restore on mount. That covered exactly two entry paths and missed every other case: in-place URL navigation, mid-flight pickup, HMR re-runs, and the gap between `setActiveChatId(B)` and the AI response that finally populates B's questions/actions. The persistence effect made it worse by writing `{chatId: activeChatId, questions: activeQuestions}` — at any moment where activeChatId had flipped before the questions were updated, sessionStorage was stamped with `{chatId: B, questions: [A's data]}` and a subsequent restore would happily render A's data for B.
+
+The root cause was that `activeQuestions` / `activeActions` / `showTaskLane` were three independent state slices implicitly assumed to be in sync with `activeChatId`. The synchronization was by convention, not by structure. Every code path that mutated them had to remember to call `resetSessionDerivedState` first; missing one created stale UI.
+
+**Decision:** Add a `taskLaneOwnerChatId` state that records *which chatId the in-memory questions/actions belong to*, set at every site that populates them (sendPrefill, selectChat, handleSend, handleTaskSubmit, handleResumeNew, refreshFacts, handleApplyFix), cleared in `resetSessionDerivedState`. The persistence effect writes ownerChatId as the chatId tag. Render is gated on `taskLaneOwnerChatId === activeChatId` and ANDed into all three render conditions (toolbar Tasks button, narrow-viewport floating drawer, main side panel). The mount-time `skipTaskLaneRestore` guard stays as belt-and-braces for the prefill/pickup entry-flash window, which the owner-gate alone doesn't cover.
+
+**Rejected:**
+- **More entry-path guards.** That's whack-a-mole — the next path nobody anticipated will reproduce the bug. The owner-gate makes the bug structurally impossible regardless of which path triggers it.
+- **Combining the four state slices into a single tagged object.** Cleaner long-term but a bigger refactor with more touch points. The owner-tracking approach gets the structural guarantee with a minimal diff and keeps the existing setState patterns.
+- **Inlining the comparison at every render site.** Works but proliferates the comparison; one named derived value (`taskLaneIsForActiveChat`) reads better and groups the gate with the persistence-effect / state declarations as a named concept.
+
+**Consequences:**
+- Stale task-lane data is structurally unable to display. The lane is hidden during any window where `ownerChatId !== activeChatId`, no matter what mutation path got you there.
+- Adding new sites that populate `activeQuestions` / `activeActions` requires also setting `taskLaneOwnerChatId`. The pattern is documented in the commit message and visible in every existing populate site as a paired call.
+- The mount-time `skipTaskLaneRestore` guard is now redundant in steady-state but kept for the few-hundred-ms flash window between component mount and the first sendPrefill / selectChat effect. Deleting it would re-introduce a (smaller) flash without strong reason.
+- Future task-lane state slices (e.g. `facts`, `activeFix`) follow the same pattern: gate their visibility on the owner check via the existing render conditions. Tagging more slices with their own `*OwnerChatId` is a future refactor if the slices diverge.
+
+---
+
 ## 2026-04-24 — Adopt dual-agent handoff system (`.ai/` + `CLAUDE.md` + `AGENTS.md`)
 
 **Context:** Claude Code hits session and weekly usage limits. Work stalls when the primary agent is locked out. Needed a structured way for OpenAI Codex to resume where Claude left off without losing architectural truth or drifting across sessions.

.ai/HANDOFF.md

@@ -2,93 +2,35 @@
 
 # HANDOFF.md
 
-**Last updated:** 2026-04-25 (America/New_York)
+**Last updated:** 2026-05-06 (Phase 1 backend complete on `feat/self-serve-signup-spec`)
 
-**Active task:** Land three open CI PRs (#150 + #151 + #152), then enable backend + e2e gates on `main`. See [CURRENT_TASK.md](CURRENT_TASK.md).
+**Active task:** Phase 1 self-serve signup backend foundation — DONE on branch. PR not yet opened.
 
-**Branches:** Three open PRs, all independent of each other for correctness:
-- `fix/ci-workflow-config` → PR #150
-- `fix/ci-pytest-xdist` → PR #151 (stacked on #150 for context but mergeable on its own)
-- `fix/e2e-test-selectors` → PR #152
+## Where this session ended
 
-**Runner setup:** Three Gitea Actions agents are now registered on the homelab box, so `backend` / `frontend` / `e2e` jobs run truly in parallel instead of serializing on a single agent. Combined with PR #151's xdist parallelization, the previous 1h 14m wall-clock should drop to ~6–10 min.
+24 commits on top of `main` (`31ca3fb`). All 26 tasks from `docs/superpowers/plans/2026-05-06-self-serve-signup-phase-1-backend.md` complete. Full pytest run is green (1167 passed, 35 deselected). Single alembic head: `c6cbfc534fad`.
 
-## Three open PRs
+Phase 1 covered: schema additions (oauth_identities, plan_billing, sales_leads, stripe_events, plus 5 new columns across users/accounts/account_invites), Subscription complimentary status + has_pro_entitlement, the two new guards (`require_active_subscription`, `require_verified_email_after_grace`), full BillingService (start_trial / create_checkout_session / apply_subscription_event / get_billing_state), Stripe webhook handler, Google + Microsoft OAuth callbacks with oauth_identities linking, OAuth-only password guard, register-time verification email + invite email-match, bulk + soft-revoke invite routes, GET /billing/state, and the pilot complimentary backfill migration.
 
-### PR #150 — `fix/ci-workflow-config` → main
+The conftest's `test_user` fixture was modified to seed a Pro/active Subscription post-register (delete-then-insert) so the new subscription guard doesn't 402 every existing test. Two existing tests adapted because they explicitly assumed the old free-plan default: `test_subscription_limits.py` (the two free-plan tests now downgrade inline) and `test_kb_accelerator.py::TestQuota::test_get_quota` (the `kb_setup` fixture downgrades to free).
 
-Carries:
-- The Codex commit (`49f8856 wip(handoff): restore backend suite to green`) — fixes 54 backend test failures.
-- Workflow fixes: `DATABASE_TEST_URL` env, `actions/upload-artifact` v3 pin.
-- Most-recent commit (`e976fb4`):
-  - Mocks `_extract_template_parameters` in `test_record_decision_persists_and_bumps_state_version` (last test failing on CI; needed an AI provider key the runner doesn't have). Verified locally — passes.
-  - pip + npm caches in all three jobs.
-  - Drops `--cov-report=term-missing` (the custom "Display coverage summary" step prints the same info from JSON).
-  - Adds `--maxfail=10` so structural breakage fails fast.
+## Resume point — DO THIS NEXT
 
-**Expected CI on this PR:** all three jobs green for the first time in months.
+1. Open the PR for branch `feat/self-serve-signup-spec`. Use `gh pr create` against `main`. Suggested title: `feat: self-serve signup backend (Phase 1)`. Body should mention dark-launch posture (every new endpoint is gated by env config, not a feature flag — see Task 26 §3 in the plan).
+2. Phase 2 (frontend + cutover) lives in a sibling plan: `docs/superpowers/plans/2026-05-06-self-serve-signup-phase-2-frontend.md` (assumed; verify path). It's the next logical task once Phase 1 ships.
 
-### PR #151 — `fix/ci-pytest-xdist` → main (stacked on #150)
+## Followups deferred from this session
 
-Carries (on top of #150):
-- `pytest-xdist==3.6.1` in `requirements-dev.txt`.
-- `conftest.py` adds `_worker_db_url` + `_ensure_worker_db_exists`. Each xdist worker gets its own DB (`resolutionflow_test_gw0`, `gw1`, …) so the per-test `DROP SCHEMA public CASCADE` doesn't race across workers.
-- Workflow's pytest invocation gains `-n auto`.
+- **OAuth callbacks don't call `_store_refresh_token`.** The Google/Microsoft callbacks issue a refresh JWT but never persist its hash to `refresh_tokens` (the password-login flow does via `auth.py:_store_refresh_token`). Result: refresh-token revocation/rotation lookups won't find OAuth-issued tokens. Decide before Phase 2 dark-launch whether to backfill — likely yes, by extracting `_store_refresh_token` to a shared module and calling it from `_sign_in_or_register`.
+- **`stripe_enabled` was relaxed** in Task 14 from `bool(STRIPE_SECRET_KEY) and bool(STRIPE_WEBHOOK_SECRET)` to just the secret key. The webhook handler in Task 16 independently checks `STRIPE_WEBHOOK_SECRET` before calling `construct_event`, so signature verification is still safe — but if any other code reads `stripe_enabled` and assumes the webhook secret is set, that's a latent bug. Audit before Phase 2 cutover.
+- **`backend/app/core/stripe_handlers.py`** is a stub module that's no longer referenced after Task 16. Safe to delete in a follow-up; left in place to keep Phase 1 diff focused.
+- **Pilot backfill migration `c6cbfc534fad` has not been applied to prod yet.** It runs once at deploy time and is forward-only.
 
-**Measured locally:** backend suite goes from `22m 27s` (serial, 1076 passed) → `4m 28s` (8 workers, 1076 passed). Same exit code, same test count.
+## Environment notes (carry-forward)
 
-### PR #152 — `fix/e2e-test-selectors` → main
-
-Carries: five Playwright e2e selector updates against the current UI. The drift was inherited from the FlowPilot/PSA migration:
-
-- `Sessions` → `Session History` (page heading)
-- `Account Settings` → `Account Management` (page heading)
-- `/assistant` → `/pilot` (Phase 1 route rename; redirect still works)
-- Flow-session filtering and the Resume button moved behind the "Flow Sessions" tab on `/sessions` (default tab is "AI Sessions")
-- `resume.spec.ts` no longer starts at `/trees` — Resume button rendering moved to the session card on `/sessions`
-
-No product-code changes. Pure test updates.
-
-## Immediate next steps
-
-1. **Merge PR #152 first.** Smallest, lowest risk, no shared file with the other two PRs.
-2. **Merge PR #150 next.** Backend test suite should be fully green (1076 passed, 0 failed, 0 errors).
-3. **Merge PR #151 last.** Backend job time drops to ~4–6 min on the runner.
-4. **Enable backend gate** on `main` branch protection — append `"CI / backend (pull_request)"` to `status_check_contexts`:
-   ```bash
-   curl -X PATCH -H "Authorization: token $GITEA_TOKEN" \
-     "https://gitea.resolutionflow.com/api/v1/repos/chihlasm/resolutionflow/branch_protections/main" \
-     -H "Content-Type: application/json" \
-     -d '{"status_check_contexts": ["CI / frontend (pull_request)", "CI / backend (pull_request)"]}'
-   ```
-5. **Then enable `CI / e2e (pull_request)`** — same PATCH, append to the list. Verify e2e is reliably green for at least one PR run before locking it in.
-
-## Uncommitted state
-
-Working tree clean (after this handoff commit).
-
-## Branch protection on main (current)
-
-- PR-only merges
-- `CI / frontend (pull_request)` required
-- Force-push blocked
-- No review required (solo)
-
-## Recently merged on main
-
-- `f27f671` — PR #149: fix(ci): frontend lint to zero errors + test-DB schema fix + dev-deps installable
-- `06593a4` — PR #148: fix(tests): repair two pre-existing bugs blocking backend CI
-- `32fae2c` — PR #147: feat: FlowPilot migration — Phase 1-9 + Phase 9 bug fixes + QA fixture harness
-- `16060d2` — PR #141: feat: PSA ticket management
-
-## Open questions
-
-- One known concern with `--maxfail=10`: if a single bad commit produces 11+ legitimate failures, CI bails before reporting them all. Acceptable trade-off — the alternative is burning 25 min on a structural break.
-- pytest-xdist load distribution is the default file-scoped balance. If one worker consistently gets the slow tests, switch to `--dist worksteal` (xdist 3.x). Not worth tuning preemptively.
-
-## Useful breadcrumbs
-
-- `backend/scripts/seed_phase9_qa_fixtures.py` pre-bakes Phase 9 QA fixtures.
-- `.gstack/qa-reports/phase9-20260424-232700/REPORT.md` — full QA report from the FlowPilot session.
-- gstack is in team mode for this repo. `/browse` Chromium needs `CONTAINER=1` env (see `~/.claude/skills/gstack/browse/src/browser-manager.ts:188`).
-- Per-worker test DBs accumulate on the postgres service. Cheap to leave around; cleanup if it ever bothers anyone.
+- Code-server LXC has bun + docker but no native python/node/npm. Use `docker exec resolutionflow_{backend,frontend} ...` for build/test commands.
+- Pytest WORKDIR is `/app` — test paths in pytest commands are `tests/<file>`, NOT `backend/tests/<file>`.
+- Backend pytest cmd: `docker exec resolutionflow_backend pytest tests/<path> -v --override-ini="addopts="`. The full run takes ~25 min.
+- Alembic via `docker exec -w /app resolutionflow_backend alembic ...`. Never pass `--rev-id`.
+- No `gh` CLI on this LXC — use the Gitea API (`$GITEA_TOKEN` in `.claude/settings.local.json`) for PR/issue work, or run `gh` from a host that has it.
+- Headless Chromium (`/qa`, `/browse`) needs `CONTAINER=1` in the env launching the browse server (LXC namespace constraint).

.ai/PROJECT_CONTEXT.md

@@ -89,6 +89,15 @@ python -m scripts.seed_trees                                        # seed (from
 
 **Never pass `--rev-id`** to alembic — let it generate the hex hash.
 
+**On hosts without native `python`/`node`/`npm`** (e.g. the code-server LXC), run commands inside the already-running containers instead:
+
+```bash
+docker exec resolutionflow_backend pytest --override-ini="addopts="
+docker exec resolutionflow_backend alembic upgrade head
+docker exec -w /app resolutionflow_frontend npm run build
+docker exec -w /app resolutionflow_frontend npx tsc -b
+```
+
 ---
 
 ## URLs & test users

.ai/SESSION_LOG.md

@@ -12,6 +12,253 @@
 
 ---
 
+## 2026-05-02 ~01:00 UTC — Claude — In-product User Guides Diátaxis rewrite shipped (PR #159)
+
+- Audited the in-product `/guides` collection against live UI via `/browse` (engineer + owner test users). Existing 15 guides predated the FlowPilot pivot — every "click X in the sidebar" reference was wrong (Dashboard → Home, All Flows → Flows, Sessions → History, Exports gone, etc.). Three guides described surfaces that no longer exist: Maintenance Flows, AI Assistant page, Flow Assist Sparkles button. Findings written to `/tmp/guides-audit.md`.
+- Rebuilt `frontend/src/data/guides.ts` from scratch as 43 problem-oriented Diátaxis how-tos under 10 categories. Single-outcome each, terse imperative steps, real UI labels (Create New, Sign in, Manage, Build New Script, Send Invite, Save Settings, Create Category, etc.). Added `category: CategoryId` and optional `relatedSlugs?: string[]` to the `Guide` interface; new `Category` type and `categories` const drive the hub layout. `GuidesHubPage` now renders category sections (auto-hides empty); `GuideDetailPage` renders a Related guides footer; `GuideCard` lost its misleading "N sections" subtitle.
+- Fixed `GuideSection.tsx`: `step.tip` was rendered as plain text so `**bold**` markdown in tips rendered literally. Applied the same regex replacement used on `step.instruction`. Verified against `/guides/start-a-session` tip block.
+- Authored 14 net-new how-tos for FlowPilot-era surfaces with no prior coverage: tasklane-keyboard-flow, view-what-we-know, ask-ai-mid-session, pause-and-leave-session, resolve-a-session, record-suggested-fix-outcome, escalate-a-session, post-docs-to-ticket, send-client-update, build-script-from-scratch, open-suggested-flow, pin-a-flow, invite-teammate. Dropped change-teammate-role from scope — couldn't verify the role-change UI control without a non-owner test member.
+- Verified owner-only surfaces with `pro@resolutionflow.example.com`: Membership inline form on `/account` (not a separate `/team-members` route), `/account/categories` real button is **Create Category** (not Add), `/account/chat-retention` real fields are **Retention Period (days)** + **Max Conversations** + **Save Settings**, `/account/integrations` form fields confirmed. Three guides corrected post-audit.
+- Smoke-tested all 43 detail pages — every slug renders, no "Guide Not Found" fallthroughs.
+- Added `100.64.78.44 docker-01` entry to `/etc/hosts` (user ran `sudo tee` from a normal terminal because the LXC `!` shell prefix can't drive interactive sudo). Should now persist across `/browse` sessions on this LXC.
+- `docker exec -w /app resolutionflow_frontend npx tsc -b` clean.
+- Files touched: `frontend/src/data/guides.ts`, `frontend/src/pages/GuidesHubPage.tsx`, `frontend/src/pages/GuideDetailPage.tsx`, `frontend/src/components/guides/GuideCard.tsx`, `frontend/src/components/guides/GuideSection.tsx`, `CHANGELOG.md`, `.ai/CURRENT_TASK.md`, `.ai/HANDOFF.md`, `.ai/SESSION_LOG.md`. Working tree dirty — user not yet asked to commit.
+
+---
+
+## 2026-05-01 21:55 UTC — Claude — Session-screen impeccable pass + tasklane keyboard flow shipped (PR #158)
+
+- Ran the `/impeccable` skill against the assistant chat session screen (chat history / chat bar / TaskLane). Initial design-health score: 24/40 with explicit DESIGN-SYSTEM violations (gradient surfaces in WhatWeKnow + ProposalBanner, side stripes in TaskLane done states + every banner mode, accent borderTop on lane header, backdrop blur on handoff overlay).
+- Walked through all 5 impeccable sub-passes (distill, quieter, layout, typeset, polish). Score after pass: 33/40 (+9). Biggest gains in Aesthetic & Minimalist (1→3), Consistency & Standards (1→3), Recognition Rather Than Recall (2→4).
+- Inline iterations on top of the impeccable steps: linked banner ↔ script-panel lifecycle (collapse hides both, dismiss closes both, any outcome closes both); collapsible WhatWeKnow with `sessionStorage` memory + auto-collapse-at-5-facts; full keyboard flow on TaskLane (Enter submits + auto-advances, Shift+Enter newline, Esc cancels, focus jumps to Send Responses after the last task).
+- Side fix: `ParameterizationPreview` was over-highlighting short parameter values (a `"D"` lit up every capital D in `Get-ADUser`/`Add-Type`/etc.). Added a word-boundary guard, conditional on whether the value itself starts/ends with a word character so values with leading punctuation (`"D:\\Folder"`) still match cleanly.
+- Followups logged in `.ai/TODO.md`: `ConcludeSessionModal` multi-select for paused/escalated outcomes (real feature work — engineers often need ≥2 of Ticket Notes / Client Update / Email Draft), and `bg-card-hover` Tailwind drift in `CommandPalette` (silently broken classes — two-line fix).
+- Branched as `feat/session-distill-quieter`, 4 commits (impeccable pass, parameterize fix, TODO followups, hint contrast + font-sans audit). PR #158 created via Gitea API (`$GITEA_TOKEN` env, no `gh` on this LXC). Merged into `main` as `5e10005`. Local branch deleted.
+- Validation at every commit boundary: `docker exec -w /app resolutionflow_frontend npx tsc -b`, `npm run lint`, and `npm run build` all clean.
+- Files touched: 14 frontend files (TaskLane, AssistantChatPage, ChatMessage, ProposalBanner, WhatWeKnow, WhatWeKnowItem, SuggestedFlowCard, ChatSidebar, ConcludeSessionModal, ChatTabStrip, ActionCardGroup, AddNoteButton, ParameterizationPreview), `.ai/TODO.md`, `.ai/CURRENT_TASK.md`, `.ai/HANDOFF.md`, `.ai/SESSION_LOG.md`, `CHANGELOG.md`, `CURRENT-STATE.md`.
+
+## 2026-05-01 07:20 UTC — Codex — Start issue cleanup plan sections 1 and 2
+
+- Started `docs/plans/2026-05-01-issue-cleanup-plan.md` sections 1 and 2.
+- Cleaned frontend lint to zero warnings by removing stale lint disables, tightening hook dependencies, and adding justified comments where effects are intentionally keyed to route or owner identity.
+- Added e2e selectors for session history controls and the FlowPilot command-palette entry.
+- Added `AssistantChatPage` observability for unexpected `currentChatRef` stale async discards.
+- Added `TaskLane` diagnostic help affordances for common command categories and documented #128 as "keep the existing responsive side-panel/bottom-drawer behavior until pilot feedback says otherwise."
+- Verified `npm run lint`, `npx tsc -b`, and `npm run build` in `resolutionflow_frontend`; build only reported the existing Vite large-chunk warning.
+- Files touched: frontend lint-cleanup files, `frontend/src/components/assistant/TaskLane.tsx`, `frontend/src/pages/AssistantChatPage.tsx`, `frontend/src/pages/SessionHistoryPage.tsx`, `frontend/src/components/layout/CommandPalette.tsx`, `docs/plans/2026-05-01-issue-cleanup-plan.md`, `.ai/HANDOFF.md`, `.ai/SESSION_LOG.md`.
+
+## 2026-05-01 06:05 UTC — Codex — Clean stale TODOs and add issue cleanup plan
+
+- Removed the resolved pytest-xdist item from `.ai/TODO.md` and reset "Up next" to no selected task.
+- Removed the resolved "Add role gate to handoff claim endpoint" backlog item from `.ai/TODO.md`.
+- Updated the frontend lint cleanup TODO from 23 warnings to the current `npm run lint` result: 24 warnings, 0 errors.
+- Tried to close Gitea #127 through the API, but this environment has no Gitea token; API returned `401 token is required`.
+- Added `docs/plans/2026-05-01-issue-cleanup-plan.md` with safe tracker actions and a recommended order for clearing remaining issues.
+- Files touched: `.ai/TODO.md`, `.ai/HANDOFF.md`, `.ai/SESSION_LOG.md`, `docs/plans/2026-05-01-issue-cleanup-plan.md`.
+
+## 2026-05-01 05:40 UTC — Codex — Audit TODO backlog and Gitea issue validity
+
+- Compared `.ai/TODO.md`, inline code TODOs, and open Gitea issues against current `main`.
+- Verified pytest-xdist is already shipped (`backend/requirements-dev.txt`, `backend/tests/conftest.py`, `.gitea/workflows/ci.yml`) so the `.ai/TODO.md` xdist item is stale. Ran frontend lint in Docker; current state is `0 errors, 24 warnings`, so the lint cleanup item remains valid but its count is stale.
+- Verified Gitea issue status: #58, #60, #128, #129, #130 remain valid; #66 is partially resolved by current `.rfflow` import/export and should be narrowed to template packs/marketplace; #127 is mostly resolved by current UI copy and prompt boundaries unless an always-visible scope badge is still wanted. Open PR #124 is stale/unmergeable against current `main`.
+- Verified inline TODOs still valid: post-session contextual feedback prompt, FlowPilot analytics domain/time-entry placeholders, prompt-cache verification note unless live telemetry has confirmed it, proposal `modify` flow editor wiring, and procedural ghost-step accept/dismiss buttons.
+- Files touched: `.ai/HANDOFF.md`, `.ai/SESSION_LOG.md`.
+
+## 2026-05-01 03:45 UTC — Claude Opus 4.7 — QA, merge, and ship PR #156 pending-verification
+
+- Committed two logical units of pending work on `feat/fix-pending-verification`: prior session's local review fixes as `5bee264` (Codex-attributed, 5 source files + 3 `.ai/` notes) and this session's docker-exec docs as `15042af` (Claude-attributed, `.ai/PROJECT_CONTEXT.md` + `AGENTS.md`). Cleaned up a 20MB `core.22120` Chromium dump left behind by an earlier sandbox crash.
+- Resolved a tooling gap surfaced by Codex's prior session ("npm/python/python3 are not on the host path") by documenting that this code-server LXC uses bun + docker for the toolchain. The `docker exec resolutionflow_{backend,frontend}` form is now the canonical command pattern in `.ai/PROJECT_CONTEXT.md`.
+- Got `$B`/Playwright Chromium running in the code-server LXC. After the user's restart cleared the AppArmor unprivileged-userns block, Chromium still aborted at the deeper `sandbox/linux/services/credentials.cc` layer because of the LXC namespace constraint. Workaround: launch browse with `CONTAINER=1` so it auto-adds `--no-sandbox`. Also added `100.64.78.44 docker-01` to code-server's `/etc/hosts` (via `docker exec -u 0`) so the headless browser could resolve the bake-in `VITE_API_URL`.
+- Drove `/qa` against the dev stack at `http://100.64.78.44:5173`. No naturally-occurring `applied_pending` fix existed in the DB, so seeded session `4a558056-bcbd-4b51-925b-248d70eb318d` and fix `cd4ff2fd-751a-4bcb-8cfa-3c77b4864fb2` into the test state (un-resolved session, swapped supersession on the two fixes). Saved a restore script first; verified DB matches pre-test state after teardown.
+- QA result: 5/7 scripted checks PASS with concrete DB + UI evidence. Banner renders correctly ("Awaiting verification" header, "Parked" tag, fix title + pending_reason, 4 actions). "Update reason" updates server-side. "It worked" → `applied_success` with `verified_at` stamped. "Dismiss" → `dismissed` with no terminal timestamp. Page-level Resolve auto-patches `applied_pending` → `applied_success` before the resolution flow opens. Page-level Escalate fires `EscalateInterceptDialog` with the generalized "still needs an outcome" copy. 2 entry-path checks (VerifyingBanner overflow, nudge "Still checking") deferred because they require live AI-generated chat state to drive; the mutating handlers behind those entry paths are verified via the tested transitions. Report at `.gstack/qa-reports/qa-report-pending-verification-2026-04-30.md`.
+- Pushed `feat/fix-pending-verification`. Polled Gitea actions runs 161; required `CI / frontend` and `CI / backend` plus `CI / e2e` all green. Merged via Gitea API as a merge commit (`3ba4532`).
+- Post-merge cleanup: fast-forwarded local `main`, deleted `feat/fix-pending-verification` locally and on the remote. Wrote handoff updates on `chore/post-156-handoff` matching the prior `chore/post-153-handoff` pattern.
+- Files touched (this session): `.ai/CURRENT_TASK.md`, `.ai/HANDOFF.md`, `.ai/PROJECT_CONTEXT.md`, `.ai/SESSION_LOG.md`, `AGENTS.md`, `.gstack/qa-reports/qa-report-pending-verification-2026-04-30.md`, `.gstack/qa-reports/screenshots/01-08*.png`. Plus the two prior-session-authored commits committed by this session (5 source + 3 `.ai/` notes).
+
+## 2026-05-01 02:24 UTC — Codex — Review-fix PR #156 pending-verification flow
+
+- Reviewed PR #156 for bugs and found three actionable gaps: pending fixes could be resolved from the page-level Resolve path without updating the fix outcome, the PendingBanner lacked the dismiss action described in the PR body, and new system-prompt examples used real-looking pending reasons contrary to the prompt anti-parrot lesson.
+- Applied fixes locally on `feat/fix-pending-verification`: page-level Resolve now patches `applied_pending` to `applied_success`; page-level Escalate now intercepts `applied_pending` before handoff; PendingBanner now has Dismiss; escalation intercept copy no longer says only "Verifying state"; generator prompts no longer include real-looking pending examples.
+- Verified via running containers: prompt anti-parrot guardrail `2 passed`, suggested-fix outcome suite `21 passed`, frontend `npx tsc -b` clean, frontend `npm run build` clean except the existing Vite large-chunk warning, and `git diff --check` clean.
+- Left for next session: browser QA PR #156 using CURRENT_TASK.md checklist, then commit/push local review fixes and merge.
+- Files touched: `backend/app/services/resolution_note_generator.py`, `backend/app/services/escalation_package_generator.py`, `frontend/src/components/pilot/ProposalBanner.tsx`, `frontend/src/components/pilot/EscalateInterceptDialog.tsx`, `frontend/src/pages/AssistantChatPage.tsx`, `.ai/HANDOFF.md`, `.ai/CURRENT_TASK.md`, `.ai/SESSION_LOG.md`.
+
+## 2026-04-30 — Claude Code — Land PR #155, ship pending-verification feature on PR #156
+
+- Committed Codex's review-pass changes (atomic conditional `UPDATE` for `claim_session`, self-claim 403, queue self-exclusion, pre-flush handoff UUID, frontend dead-code removal) as `f10649a` on `feat/escalation-metric-endpoint`.
+- Pushed `feat/escalation-metric-endpoint`, un-drafted PR #155, retitled it (stripped "WIP:"), and merged via Gitea API as a merge commit (`ac42f97`). 4/4 CI checks green at merge.
+- Picked up follow-up work surfaced by the user: the suggested-fix verifying banner forces a synchronous verdict, but real fixes are often async (waiting on client power-cycle, AD replication, license sync). Added a fourth, non-terminal outcome.
+- Designed the model: new `FixStatus="applied_pending"` parallel to `applied_partial`. Distinct semantics — partial = "did some of it"; pending = "did all of it, can't verify yet." Distinct prose in the resolution-note + escalation-package generators.
+- Implemented on a fresh branch `feat/fix-pending-verification` off main:
+  - Backend: extended `FixStatus`/`FixOutcome` literals, added `pending_reason` Text column and CHECK constraint update via Alembic migration `c0f3a4b7e91d`. `patch_outcome` accepts pending, requires notes, stamps `applied_at` only (NOT `verified_at`); pending in/out transitions allowed.
+  - Frontend: new `BannerMode='pending'` + `PendingBanner` component (info-tone, mirrors `PartialBanner`). "Waiting to verify…" added to `VerifyingBanner` overflow menu. `NudgeBanner` "Still checking" button now records `applied_pending` with a reason instead of just silencing for the session — closes the loop semantically. `AssistantChatPage` banner-mode derivation maps the new status.
+  - Tests: 4 new integration tests in `test_fix_outcome_endpoint.py` covering notes-required, reason-storage with applied_at-not-verified_at semantics, pending→success transition, and pending_reason update on re-PATCH. 21/21 pass.
+- Validation: `tsc --noEmit -p tsconfig.app.json` exit 0; `alembic upgrade heads` applied cleanly.
+- Single-commit PR #156 opened: https://gitea.resolutionflow.com/chihlasm/resolutionflow/pulls/156. Branch rebased onto post-merge main.
+- Cleanup: removed 10 stray `core.*` dumps from the worktree; deleted merged `feat/escalation-metric-endpoint` locally and on the remote.
+- Files touched: `backend/app/models/session_suggested_fix.py`, `backend/app/schemas/session_suggested_fix.py`, `backend/app/api/endpoints/session_suggested_fixes.py`, `backend/app/services/resolution_note_generator.py`, `backend/app/services/escalation_package_generator.py`, `backend/tests/test_fix_outcome_endpoint.py`, `backend/alembic/versions/71efd2102f49_add_pending_status_to_suggested_fixes.py`, `frontend/src/api/sessionSuggestedFixes.ts`, `frontend/src/components/pilot/ProposalBanner.tsx`, `frontend/src/pages/AssistantChatPage.tsx`, `.ai/CURRENT_TASK.md`, `.ai/HANDOFF.md`, `.ai/SESSION_LOG.md`, `.ai/DECISIONS.md`.
+
+---
+
+## 2026-04-30 06:25 UTC — Codex — Apply Escalation Mode review fixes
+
+- Reviewed the recent Escalation Mode wedge work and fixed the actionable findings before PR #155 is marked ready.
+- Reworked `HandoffManager.claim_session` from read-then-write to an atomic conditional update, preserving idempotent same-user retries and returning a typed conflict for a different claimant.
+- Blocked original engineers from claiming their own handoffs and filtered their own escalated sessions out of `/ai-sessions/escalation-queue`, preventing the post-escalation dashboard from showing a junior their own handoff.
+- Fixed the compatibility payload so `session.escalation_package["handoff_id"]` is populated from a preassigned UUID before flush.
+- Removed unused legacy frontend pickup state (`claiming`, `handleStartHere`, unused `onStartHere` destructuring) that made `tsc -b` fail under `noUnusedLocals`.
+- Added regression coverage for pre-flush handoff IDs, conflict handling, self-claim rejection, successful non-owner claim, and own-escalation queue exclusion.
+- Verified `git diff --check`; focused backend tests passed (`28 passed in 42.23s`); frontend `tsc --noEmit` checks passed for app and node configs. Full Vite/build script remains blocked by root-owned generated directories under `frontend/node_modules` / `frontend/dist` in this workspace, not by TypeScript errors.
+- Files touched: `backend/app/services/handoff_manager.py`, `backend/app/api/endpoints/ai_sessions.py`, `backend/app/api/endpoints/session_handoffs.py`, `backend/tests/test_handoff_manager.py`, `backend/tests/test_session_handoffs_api.py`, `frontend/src/components/flowpilot/HandoffContextScreen.tsx`, `frontend/src/pages/AssistantChatPage.tsx`, `.ai/HANDOFF.md`, `.ai/SESSION_LOG.md`.
+
+## 2026-04-30 — Claude Code — Browser QA pass complete; chat ownership bug found and fixed; PR #155 ready
+
+- Ran full browser QA pass on the escalation mode feature using gstack `/qa` skill.
+- **Critical bug found and fixed (commit `dc69c9d`):** `POST /ai-sessions/{id}/chat → 400` when senior clicked "Get AI analysis" on the magic-moment screen. Root cause: `unified_chat_service.send_chat_message` checked `AISession.user_id == user_id` only; senior is stored as `escalated_to_id`, not `user_id`. Fix: `or_(AISession.user_id == user_id, AISession.escalated_to_id == user_id)` in the WHERE clause.
+- **All 7 QA scenarios passed:**
+  - Post-escalation redirect: junior routed to `/` with "Session escalated" toast.
+  - Magic-moment screen: header, metadata, two-column AI assessment, 2-option CTA rendered correctly.
+  - "I'll take it from here": claim → dismiss overlay → composer focused.
+  - "Get AI analysis": claim → briefing sent → AI responded → task lane populated (after `dc69c9d` fix).
+  - Task lane copy button: toast + checkmark visual feedback.
+  - Chip expansion: inline detail card + "Open in Tasks panel" scroll.
+  - Post-claim toolbar re-open: dismissible mode with Close-only CTA.
+- **Known non-blockers:** "Continue where X left off" path untestable on first pickup (`hasTaskLane=false` is correct v1 behavior). 409 race condition untestable with one senior account; backend logic code-reviewed and correct.
+- Backend tests: 17/17 pass.
+- Updated `HANDOFF.md` to reflect QA complete; updated `CURRENT_TASK.md` status to engineering+QA complete; appended architectural decision to `DECISIONS.md`.
+- Branch `feat/escalation-metric-endpoint` is ready for PR #155 to be marked ready-for-review.
+- **Files touched this session:** `backend/app/services/unified_chat_service.py`, `.ai/HANDOFF.md`, `.ai/CURRENT_TASK.md`, `.ai/DECISIONS.md`, `.ai/SESSION_LOG.md`.
+
+---
+
+## 2026-04-29 04:30 EDT — Claude Code — Live QA bash, pickup bug fixes, AI summary consolidation surfaced
+
+- User on a freshly swapped computer ran the live QA flow. Identified two bugs missed by static analysis from the previous session:
+  - **Pickup landed on a blank chat surface.** Root cause: commit `8914391` had made `activeChatId` initialize from `urlSessionId`, which broke the selectChat-gating effect in `AssistantChatPage` (`urlSessionId === activeChatId` short-circuited fresh mounts). Symptom was `selectChat` never firing post-claim; messages, conversation history, and pickup-flow correctness all silently broken.
+  - **Picked-up session missing from sidebar.** Root cause: `loadChats` runs once at mount; pre-claim the session's `escalated_to_id` is null (the junior didn't specify a target), so `listSessions` doesn't return it. Post-claim `claim_session` sets `escalated_to_id` to teamadmin, but the sidebar list never refreshes.
+- Fixes (commit `0d1b305`):
+  - Replaced the `urlSessionId === activeChatId` gate with a `loadedChatIdsRef` set so selectChat fires once per URL session per page lifecycle, regardless of whether activeChatId already matches.
+  - Added `loadChats()` call in `handleStartHere` after the claim succeeds so the sidebar reflects ownership.
+- Three additional pieces folded into `0d1b305` from the same QA bash:
+  - **Enter-to-submit on the escalate forms.** Chat-input convention: plain Enter submits, Shift+Enter inserts a newline. Added optional `onSubmit` prop to `RichTextInput` (used by `EscalateModal`) and inline `onKeyDown` on the plain textarea in `ConcludeSessionModal`. The user explicitly asked for this — they want to type the reason and hit Enter without reaching for the mouse.
+  - **Dashboard `PendingEscalations` rows expand to preview.** Click a row to reveal escalation reason + step count + confidence tier + PSA ticket number. Pick Up button click-stops to still go directly to magic moment. Single expansion at a time.
+  - **`ESCALATION_AI_ASSESSMENT_TIMEOUT_SECONDS` bumped 15 → 45.** Backend logs showed Sonnet hitting the 15s timeout in field testing. Background-task architecture (e8ba74e) means this no longer blocks the user — only bounds before publishing `has_assessment: false`. **Did NOT fix the live demo.** Assessment placeholder still permanent in user's test.
+- Surfaced an architectural smell: the escalation flow makes **three** Sonnet calls — `_build_escalation_package_enhanced`, `_generate_ai_assessment`, and `generate_status_update` (engineer-triggered) — all summarizing the same source material from slightly different angles. User correctly observed: status update is typically generated during the escalate flow anyway; reusing that content would consolidate.
+- Decided the right consolidation: ONE structured AI call per escalation that returns both the magic-moment diagnostic fields (`likely_cause`, `suggested_steps[]`, `confidence`) AND PSA-ready prose. Magic moment populates immediately. Status update buttons become tone-shift transformations (Haiku) of the saved prose, not fresh summarizations. Drops to 1 call (~60% token reduction), eliminates the AI-summary placeholder bug because the work happens in the foreground escalate path. Full implementation plan written into CURRENT_TASK.md and DECISIONS.md.
+- Session ended pre-consolidation: user is updating Claude Code CLI and starting a fresh session for clean context window. All work pushed to origin (`0d1b305`). PR #155 still draft.
+- Test users for the next session (Acme MSP shared account, password `TestPass123!`): `engineer@` (junior) and `teamadmin@` (senior).
+- Files touched: `frontend/src/pages/AssistantChatPage.tsx`, `frontend/src/components/common/RichTextInput.tsx`, `frontend/src/components/flowpilot/EscalateModal.tsx`, `frontend/src/components/assistant/ConcludeSessionModal.tsx`, `frontend/src/components/dashboard/PendingEscalations.tsx`, `backend/app/core/config.py`, `.ai/CURRENT_TASK.md`, `.ai/HANDOFF.md`, `.ai/SESSION_LOG.md`, `.ai/DECISIONS.md`.
+
+## 2026-04-28 02:00 EDT — Claude Code — Plan-locked wedge polish + structural task-lane fix
+
+- Audited `docs/plans/2026-04-27-escalation-mode-wedge-design.md` against the branch and identified four locked-design / Codex-correction items not yet shipped: live AI assessment refresh, suggested-step chips, unread 6px dot on queue cards, and race-condition toast on claim conflict.
+- Shipped all four in commit `0f00ee5`:
+  - **Live AI assessment refresh.** New `HandoffAssessmentReadyEvent` type and `onAssessmentReady` handler on `streamEscalations`. `AssistantChatPage` opens a scoped SSE subscription whenever it tracks a handoff missing its AI assessment; on a matching event it calls `handoffsApi.listHandoffs(sessionId)`, finds the handoff by id, and replaces both `magicHandoff` and `overlayHandoff` in place. Closes the loop on the async-assessment commit `e8ba74e` — without this, the senior had to manually reopen the Context overlay to see the AI assessment when the background task finished.
+  - **Suggested-step chips.** New `chipsHidden` state in `AssistantChatPage`; chip strip renders above the composer when the magic-moment dissolves and `magicHandoff?.ai_assessment_data?.suggested_steps[]` is non-empty. Click prefills input and focuses; first send via `handleSend` flips `setChipsHidden(true)`; explicit X button also hides. Per-session lifetime by design (Codex correction locked).
+  - **Unread 6px dot.** localStorage-backed seen set (`rf-escalation-seen`, capped at 200 entries) hydrated in `EscalationQueue`. Card render adds a 6px `bg-accent` dot when not in the seen set. `markSeen` called on Pick Up click AND on card body click (the "open" affordance). Hover deliberately doesn't clear (Codex correction). Pick Up button's onClick now calls `e.stopPropagation()` so it doesn't double-fire the card-open path.
+  - **Race-condition toast on claim conflict.** New `HandoffAlreadyClaimedError` exception class in `handoff_manager.py`. `claim_session` now eager-loads `claimed_by_user` via `selectinload`, rejects different-user re-claims (idempotent for same-user double-clicks), and raises with `claimed_by_id` / `claimed_by_name` / `claimed_at`. The endpoint translates to HTTP 409 with structured `detail = {error: 'already_claimed', claimed_by_id, claimed_by_name, claimed_at}`. `AssistantChatPage.handleStartHere` extracts via `axios.isAxiosError`, formats `"Already claimed by {name} {time_ago}."` using the existing `timeAgo()` helper, drops `?pickup=true`, and dismisses the magic-moment so the loser flows back to the queue. Backed by 2 new unit tests (`test_claim_session_conflict_raises_already_claimed`, `test_claim_session_idempotent_for_same_user`).
+- User then reported that the task-lane stale-flash bug was still happening despite the prior fix `8914391` — "every time we work on something that's related to this, when we go back to test we create a new session and then the task lane shows unrelated session data." The previous fix only covered mount-time entry paths (prefill + pickup); any in-place transition still flashed.
+- Shipped structural fix in commit `665530f`. Introduced `taskLaneOwnerChatId` state that explicitly tags which chatId the in-memory `activeQuestions` / `activeActions` / `showTaskLane` values belong to. Set at every populate site (sendPrefill, selectChat, handleSend, handleTaskSubmit, handleResumeNew, refreshFacts, handleApplyFix). Cleared in `resetSessionDerivedState`. Persistence effect now writes `chatId: taskLaneOwnerChatId` (was `activeChatId` — that was the original write-side bug). Render gate `taskLaneIsForActiveChat = ownerChatId === activeChatId` ANDed into all three render conditions. The lane is structurally unable to display data tagged with a different chat. See DECISIONS entry. **Not yet verified in a real browser** — user is swapping computers and asked for the handoff first.
+- The two commits `0f00ee5` and `665530f` are **local-only** at session end. The user did not explicitly authorize a push, so per the handoff rule the branch was left unpushed. First action on resume is `git push`.
+- Tests: full handoff + escalation suite (`test_handoff_manager.py`, `test_session_handoffs_api.py`, `test_escalation_bus.py`, `test_flowpilot_analytics_escalations.py`) → 34 passed in 68.89s. Frontend `tsc -b` exit 0 after each commit.
+- Files touched: `frontend/src/api/aiSessions.ts`, `frontend/src/components/flowpilot/EscalationQueue.tsx`, `frontend/src/pages/AssistantChatPage.tsx`, `frontend/src/types/ai-session.ts`, `backend/app/api/endpoints/session_handoffs.py`, `backend/app/services/handoff_manager.py`, `backend/tests/test_handoff_manager.py`, `.ai/CURRENT_TASK.md`, `.ai/HANDOFF.md`, `.ai/SESSION_LOG.md`, `.ai/DECISIONS.md`.
+
+## 2026-04-27 22:30 EDT — Claude Code — Escalation Mode: unify /escalate through HandoffManager
+
+- User pushed back on the dual-path proposal: "why would we want two different escalation methods? Should the new one just be the way we escalate regardless if we're using a PSA or not using a PSA?" Right answer. Unified everything through `HandoffManager`.
+- Backend changes (commit `029680a`):
+  - `HandoffCreateRequest` gains optional `target_user_id`; rejects self-targeting.
+  - `HandoffManager.create_handoff` for intent='escalate' now does what the legacy `flowpilot_engine.escalate_session` used to: sets `session.escalation_reason` and `escalated_to_id`, builds the legacy AI-enhanced `escalation_package` via Sonnet (`_build_escalation_package_enhanced` lazy-imported with graceful fallback), and merges handoff metadata (`intent`, `handoff_id`, `snapshot`, `engineer_notes`) into it. Eager-loads `session.steps` + `session.user` via `selectinload` to dodge async lazy-load `MissingGreenlet` errors.
+  - New `HandoffManager.finalize_escalation`: generates `SessionDocumentation`, pushes to PSA, and runs `notify()` (bell-icon AppNotification + Slack/Teams external channels) — all pre-commit so persistent state lands atomically with the handoff. Pulls engineer name via a separate User query rather than relying on `session.user` lazy access.
+  - `dispatch_escalation_notifications` keeps only the fire-and-forget IO (bus publish + per-user emails) post-commit. Found and fixed an in-flight bug: had originally put `notify()` inside dispatch (post-commit), which left `Notification` rows uncommitted — moved into `finalize_escalation` (pre-commit).
+  - `/handoff` endpoint passes `target_user_id` through and calls `finalize_escalation` pre-commit.
+  - `/escalate` is now a thin shim: owner-only session lookup → `create_handoff(intent='escalate')` → `finalize_escalation` → commit → `dispatch_escalation_notifications` → return `SessionCloseResponse`. `flowpilot_engine.escalate_session` is no longer called by any endpoint.
+  - `pickup_session` accepts both `requesting_escalation` (legacy in-flight) and `escalated` (new canonical) so existing queue items migrate seamlessly.
+  - Escalation queue list (`/escalation-queue`) and sidebar count match either status.
+- Frontend: `useFlowPilotSession` optimistic update flips status to `escalated` instead of `requesting_escalation` so the page state matches the unified backend response.
+- Verified end-to-end live against the running dev stack: a single legacy `/escalate` call from `engineer@` produced status=`escalated`, a `SessionHandoff` row (`ea9b375a…`, intent='escalate'), a `SessionDocumentation`, a PSA push attempt (`no_psa` since no ticket), AND an `AppNotification` for `teamadmin@` with title "Session escalated by Jordan Tech" and link `/pilot/{session_id}?pickup=true`. Backend test suite: `1103 passed in 259.63s` with `-n auto`. Frontend `tsc -b` clean.
+- The legacy `SessionBriefing` render branch in `FlowPilotSessionPage.tsx` is now effectively dead for any new escalation (magic-moment takes over via the handoff record), but stays in place during the transition for legacy in-flight `requesting_escalation` sessions. Slated for cleanup after pilots run a couple of weeks on the unified path. `flowpilot_engine.escalate_session` is similarly orphaned and can be deleted at the same time.
+- Files touched: `backend/app/api/endpoints/ai_sessions.py`, `backend/app/api/endpoints/session_handoffs.py`, `backend/app/api/endpoints/sidebar.py`, `backend/app/schemas/session_handoff.py`, `backend/app/services/flowpilot_engine.py`, `backend/app/services/handoff_manager.py`, `frontend/src/hooks/useFlowPilotSession.ts`.
+
+## 2026-04-27 21:50 EDT — Claude Code — Escalation Mode: bell-icon notification fix; push + draft PR
+
+- User ran a live escalation test via the EscalateModal (legacy `/escalate` path) and reported that clicking the bell-icon notification "just clears the notification instead of taking me to the session". Diagnosed: navigation IS happening, but the notification link template was `/pilot/{session_id}` without `?pickup=true`, so the senior landed on `FlowPilotSessionPage` with no pickup mode. `loadSession` then hit `GET /ai-sessions/{id}` which 404'd because the senior wasn't owner / `escalated_to_id` / picked-up handler. The user perceived the resulting error state as the action having done nothing.
+- Two-part backend fix shipped in `641853a`. (1) `_build_notification_link` for `session.escalated` now ends with `?pickup=true` so notification clicks route through the senior-pickup flow (handoff-based or legacy SessionBriefing). (2) `GET /ai-sessions/{id}` access policy: any account member can now read a session's detail when status is `requesting_escalation` or `escalated`. Tenant boundary enforced by RLS — the owner-only guard was overly restrictive for explicitly-shared in-transit states. After-pickup access (handler / `escalated_to_id`) checks still apply for active/resolved sessions.
+- Verified end-to-end live: re-login as senior engineer (non-owner, non-target) and `GET /ai-sessions/{escalated-session-id}` returns 200 with full detail. Backend regression with broader subset (`test_escalation_bus`, `test_handoff_manager`, `test_session_handoffs_api`, `test_flowpilot_analytics_escalations`, `test_sessions`, `test_session_sharing`) → 94 passed in 43.26s.
+- Pushed `feat/escalation-metric-endpoint` to Gitea. Opened **draft PR #155** against `main` via Gitea API ([gitea.resolutionflow.com/chihlasm/resolutionflow/pulls/155](https://gitea.resolutionflow.com/chihlasm/resolutionflow/pulls/155)). Title prefixed `WIP:` so Gitea marks it `draft: true`. PR body links the design + test-plan artifacts and mirrors the test plan as a checklist with visual QA + e2e demo flow as the unchecked items.
+- Open question for next session: EscalateModal still calls the legacy `/escalate` endpoint, not the new `/handoff` path. The wedge demo flow (junior escalates → magic-moment renders) is cleaner if EscalateModal goes through `/handoff`. Legacy path does PSA documentation push that the handoff path doesn't, so a parallel path (legacy escalate also creates a handoff record) is probably the right call rather than full migration.
+- Files touched: `backend/app/api/endpoints/ai_sessions.py`, `backend/app/services/notification_service.py`, `.ai/CURRENT_TASK.md`, `.ai/HANDOFF.md`, `.ai/SESSION_LOG.md`.
+
+## 2026-04-27 21:30 EDT — Claude Code — Escalation Mode: magic-moment handoff-context screen on pickup
+
+- Continued the same session that shipped the live-arrival SSE subscription. Added the magic-moment screen on top.
+- New `frontend/src/components/flowpilot/HandoffContextScreen.tsx`: presentational 4-section view (header with problem summary + domain + step count + escalated-time + priority badge; "What's been tried" with engineer notes + step-count affordance; "AI assessment" with likely_cause / suggested_steps / confidence badge; "Start here" CTA). Confidence badge accepts both numeric (0..1) and string ("low"/"medium"/"high") shapes — backend emits the latter, the frontend type says `number`, runtime handles both. Renders an explicit "assessment unavailable — model didn't respond in time" branch when `ai_assessment_data` is null (the 5s timeout from `9bdd995` fired). `prefers-reduced-motion` swaps `animate-slide-up` for `animate-fade-in`. ARIA `role=dialog` + `aria-modal=true` + focus on primary CTA on mount + Esc dismiss when used as a re-openable overlay.
+- Integration in `frontend/src/pages/FlowPilotSessionPage.tsx`: on `/pilot/:id?pickup=true`, fetch the handoff list via `handoffsApi.listHandoffs` (account-scoped via RLS, no claim required) and find the latest unclaimed escalate handoff. If found, render the screen and skip `loadSession` (the senior would 404 pre-claim because they aren't yet `escalated_to_id`). "Start here" calls `handoffsApi.claimHandoff`, drops the `?pickup=true` query, and dismisses the screen — the existing `loadSession` effect then fires because the senior is now `escalated_to_id`. New "Context" toolbar button on active sessions (visible only when the senior arrived via the magic-moment flow this session — handoff lookup on demand) re-opens the screen as a dismissible overlay.
+- Verified end-to-end against the running dev stack: `listHandoffs` returns the unclaimed handoff with full payload (engineer_notes, snapshot keys); `claimHandoff` flips session status from `escalated` → `active` and sets `escalated_to_id`; subsequent `GET /ai-sessions/{id}` succeeds. `tsc -b` exit 0. No backend changes; backend tests still `32 passed in 18.91s`.
+- Deferred to TODOs in `CURRENT_TASK.md`: suggested-step chips below the chat input (Codex correction; threads through to `FlowPilotMessageBar`); `HandoffManager._generate_snapshot` expansion to include the recent diagnostic timeline pre-claim (today's snapshot is just `problem_summary, problem_domain, status, step_count, confidence_tier`); toolbar "Context" button visibility on revisited active sessions; owner-facing `/analytics/escalations` page; Playwright e2e for the GTM Loom demo path.
+- Branch state: 3 new commits (`b8627f4` SSE subscription, `f65b657` handoff doc bump, `8e9d22e` magic-moment screen). Branch is unpushed — next session pushes + opens draft PR.
+- Files touched this slice: `frontend/src/components/flowpilot/HandoffContextScreen.tsx` (new), `frontend/src/components/flowpilot/index.ts`, `frontend/src/pages/FlowPilotSessionPage.tsx`, `.ai/CURRENT_TASK.md`, `.ai/HANDOFF.md`, `.ai/SESSION_LOG.md`.
+
+## 2026-04-27 21:00 EDT — Claude Code — Escalation Mode: frontend SSE subscription in EscalationQueue
+
+- Picked up `feat/escalation-metric-endpoint` after the Codex test-stabilization pass. Confirmed green starting state: focused backend subset `32 passed in 18.78s` with `-n auto`.
+- Implemented the live-arrival frontend slice. Added `streamEscalations(handlers, signal)` to `frontend/src/api/aiSessions.ts` — fetch-based `ReadableStream` reader (native `EventSource` can't send auth headers) that parses SSE frames (event/data/comment lines), buffers partial frames across chunks, ignores `: keepalive` heartbeats, dispatches `ready` and `handoff_created` events. Added `HandoffCreatedEvent` and `EscalationStreamHandlers` types in `frontend/src/types/ai-session.ts` mirroring the backend bus payload.
+- Rewrote `frontend/src/components/flowpilot/EscalationQueue.tsx`. SSE subscription with `AbortController` + exponential-backoff reconnect (1s → 30s cap, attempt counter resets on `ready`). On `handoff_created` the component refetches the queue, diffs against the previous IDs via a `sessionsRef`, prepends new arrivals (newest-first) above established cards (oldest-first preserved). New IDs are tagged for 800ms so the locked 200ms slide-in animation plays before cleanup. Tab-title flash: captures `document.title` at mount, prefixes `(N)` while `document.hidden`, clears on `focus` / `visibilitychange`, restores on unmount. `prefers-reduced-motion: reduce` swaps `animate-slide-in-bottom` for `animate-fade-in`. ARIA: `role="region"` + `aria-live="polite"` on the list, `aria-label="N escalations awaiting pickup"` on the heading; Pick Up button bumped to `py-2.5` to clear the 44px touch floor.
+- Verified end-to-end against the running dev stack. `tsc -b` exit 0. Vite HMR'd the new component without errors. Raw SSE handshake against `/api/v1/ai-sessions/escalations/stream` returned 200 with `text/event-stream; charset=utf-8` plus the locked headers (`cache-control: no-cache`, `x-accel-buffering: no`). Subscriber received the `ready` frame on connect; after posting a handoff via the API, the subscriber received the `handoff_created` frame with the full payload — wire format matches the parser exactly. Backend regression: same focused subset still `32 passed in 18.91s`.
+- Not yet verified (would need a real browser session): the slide-in animation visually plays, the tab title actually updates, the reduced-motion media-query path, AbortController cancellation on unmount, backoff after a real network blip. Wire contract is confirmed; these are visual/timing-dependent and follow from correct parser + state machine.
+- Smoke-test artifact: a single test handoff (`0f6149db…` on session `50ea20d4…`) is sitting in the engineer's queue from the verification step. Harmless; useful as visual demo data.
+- Left for next session: the magic-moment handoff-context screen — 4 sections (problem summary / what's been tried / AI assessment / Start here CTA), loads on Pick Up, dissolves into the regular FlowPilot session view. Must render gracefully when `ai_assessment` is `None` (per the 5s assessment timeout from Codex's earlier fix).
+- Files touched: `frontend/src/api/aiSessions.ts`, `frontend/src/types/ai-session.ts`, `frontend/src/components/flowpilot/EscalationQueue.tsx`, `.ai/CURRENT_TASK.md`, `.ai/HANDOFF.md`, `.ai/SESSION_LOG.md`.
+
+## 2026-04-27 EDT — Claude Code — Escalation Mode wedge: design through SSE backend (8 commits)
+
+- One long session that produced the entire planning artifact stack and most of the backend for the Escalation Mode wedge. Output of `/office-hours` (8 founder-signal session, top-tier YC archetype indicators), `/plan-eng-review` (scope reduced from "2-3 weeks greenfield" to "~6-9 days integration + metric + polish" once the existing handoff_manager surface was inventoried), `/plan-design-review` (6/10 → 9/10 with magic-moment screen, hero metric placement, and real-time arrival visual locked), and `/codex review` (12 findings, 6 applied — two-metric framing, notification routing, claim auth gate moved in-scope, unread-state fix, "Start here" CTA reframe, per-channel delivery model; 5 rejected including the full-scope reduction Codex pushed for).
+- Branched `feat/escalation-metric-endpoint` off `main` @ `c0ed6d9`. Stack at session end: `d51e95c` plan + test-plan artifacts; `52f6d03` `GET /analytics/flowpilot/escalations` endpoint with 9 tests including multi-tenant isolation; `7a5b853` claim-endpoint role gate; `07d0db9` email dispatch on escalate with graceful-degradation regression; `9f0bfd4` `EscalationMetricCard` mounted above the queue list; `a283d0d` mid-flight `.ai/` refresh; `87bd0b7` WIP commit for SSE pub/sub bus + endpoint + 7 bus unit tests + 1 dispatcher integration test + 2 endpoint tests; `ba46fc5` paused-for-Codex-review handoff. Codex picked up from `ba46fc5` and added `bc15952` / `fff8338` / `9bdd995` (test stabilization + assessment latency bound).
+- Pause was forced by a runaway local test loop: multiple stale `pytest` processes were left inside `resolutionflow_backend` after several aborted runs and contended on the same Postgres test schema. Codex diagnosed and fixed (see entry above).
+- Frontend: thin slice — added `getEscalationMetrics` to `flowpilotAnalyticsApi`, the `EscalationMetricCard` component (loading / error / zero-data states + avg + median + conversion-rate + the inline two-metric disclaimer), and mounted it above `EscalationQueue`. `tsc -b` clean.
+- Plan-stage UI decisions locked into the design doc and the codebase: dedicated 4-section magic-moment screen on Pick Up that dissolves into FlowPilot; queue stat-card + dedicated owner analytics page for the hero metric (in two places, not one); 200ms slide-in + tab-title flash on real-time arrival, no sound, respects `prefers-reduced-motion`; unread dot clears on open/claim/dismiss, NOT on hover (Codex correction). Claim role gate moved in-scope per Codex (not deferred to TODO).
+- Two TODOs added: peer-tech escalation (deferred to v2 once a pilot asks); mobile/responsive design (also v2; pre-PMF wedge demo targets desktop). Claim role gate's TODO entry was struck through in the same session because it shipped in `7a5b853`.
+- Plan and test-plan artifacts copied into `docs/plans/` under the `YYYY-MM-DD-name-design.md` / `-test-plan.md` convention so they live alongside the existing project plans, not just in `~/.gstack/projects/`.
+- Left for next session: frontend SSE subscription in `EscalationQueue.tsx` (fetch-based ReadableStream — native EventSource can't send auth headers; match `streamDocumentation` in `frontend/src/api/aiSessions.ts`), then the magic-moment handoff-context screen, then push + draft PR. Default Claude Code model is being switched from Opus 4.7 1M-context to Opus 4.7 (200k) for the next session — the resume docs are sized to be self-sufficient under the smaller window.
+- Files touched (committed): `docs/plans/2026-04-27-escalation-mode-wedge-design.md`, `docs/plans/2026-04-27-escalation-mode-wedge-test-plan.md`, `backend/app/api/endpoints/flowpilot_analytics.py`, `backend/app/schemas/flowpilot_analytics.py`, `backend/app/api/endpoints/session_handoffs.py`, `backend/app/services/handoff_manager.py`, `backend/app/core/escalation_bus.py` (new), `backend/tests/test_flowpilot_analytics_escalations.py` (new), `backend/tests/test_escalation_bus.py` (new), `backend/tests/test_handoff_manager.py`, `backend/tests/test_session_handoffs_api.py`, `frontend/src/types/flowpilot-analytics.ts`, `frontend/src/api/flowpilotAnalytics.ts`, `frontend/src/components/flowpilot/EscalationMetricCard.tsx` (new), `frontend/src/components/flowpilot/index.ts`, `frontend/src/pages/EscalationQueuePage.tsx`, `.ai/CURRENT_TASK.md`, `.ai/HANDOFF.md`, `.ai/TODO.md`.
+
+## 2026-04-27 19:50 EDT — Codex — Stabilize Escalation Mode SSE backend tests
+
+- Diagnosed slow backend tests on `feat/escalation-metric-endpoint`. Multiple stale pytest processes were still alive inside `resolutionflow_backend` and held `resolutionflow_test` transactions open, blocking later per-test schema resets on `DROP SCHEMA public CASCADE`.
+- Reproduced a deterministic hang in `test_escalations_stream_returns_sse_content_type`: HTTPX `ASGITransport` buffers the full response body before returning, so an infinite SSE response never yielded the initial chunk and kept the auth DB dependency transaction open.
+- Fixed `stream_escalations` to release auth dependencies before the long-lived stream body with `Depends(..., scope="function")`.
+- Reworked the SSE handshake test to call `stream_escalations()` directly and consume one generator yield, then close it; kept viewer role-gate coverage through the API client.
+- Stubbed `_generate_ai_assessment()` in handoff manager/API tests so escalation handoff tests no longer wait on the real AI path.
+- Normalized account IDs inside `EscalationBus` so string UUIDs and `UUID` objects hit the same subscriber bucket; added a regression test.
+- Verified focused backend subset: serial `31 passed in 46.95s`; xdist `31 passed in 17.80s`. Confirmed no lingering pytest processes or test DB sessions afterward.
+- Follow-up in the same session: fixed the product latency risk by adding `ESCALATION_AI_ASSESSMENT_TIMEOUT_SECONDS` (default 5s) around escalation AI assessment generation. If the optional assessment times out, handoff creation continues with no assessment. Added regression coverage; focused xdist subset now `32 passed in 17.77s`.
+- Left for next session: continue frontend SSE subscription in `EscalationQueue.tsx`, then the magic-moment handoff-context screen.
+- Files touched: `backend/app/api/endpoints/session_handoffs.py`, `backend/app/core/config.py`, `backend/app/core/escalation_bus.py`, `backend/app/services/handoff_manager.py`, `backend/tests/test_escalation_bus.py`, `backend/tests/test_handoff_manager.py`, `backend/tests/test_session_handoffs_api.py`, `.ai/HANDOFF.md`, `.ai/SESSION_LOG.md`, `.ai/TODO.md`.
+
+## 2026-04-26 03:50 EDT — Claude Code — Ship AssistantChatPage prefill `currentChatRef` fix; close out PR #150
+
+- User reported a troubleshooting-session bug: after answering a subset of task-lane questions and clicking *Send N of M Responses*, no AI response appeared. Traced to `AssistantChatPage`: the dashboard prefill effect set `activeChatId` after creating a new chat session but never updated `currentChatRef.current`. The `currentChatRef.current !== sentForChatId` guard in `handleSend` and `handleTaskSubmit` then bailed silently on every later request and discarded the AI's reply. The user message was already pushed to the chat before the await, so the user saw their answers but nothing else.
+- Fix: one-line addition mirroring `handleNewChat` and `handleResumeNew` — assign `currentChatRef.current = session.session_id` immediately after `setActiveChatId(session.session_id)` in the prefill effect. Branched off `origin/main` as `fix/tasklane-prefill-ref`; PR #153 opened on Gitea.
+- Authored a Playwright regression test `frontend/e2e/assistant-chat-prefill.spec.ts` that drives the real dashboard prefill flow against the real backend, stubs `/ai-sessions/*/chat` with `page.route` for deterministic turn-1/turn-2 responses, and asserts the second AI message renders. Confirmed the test fails on unfixed code at the exact assertion (`Got it — based on your answer…` never appears) and passes once the fix is restored.
+- Verified locally inside `mcr.microsoft.com/playwright:v1.58.2-noble` against the running dev stack: new spec passes, adjacent `flowpilot-chat` spec still passes, `tsc -b` clean. `resume.spec` and `history.spec` failures observed are pre-existing real-backend fixture collisions, unrelated to this change.
+- First CI run on PR #153 failed on infrastructure issues already addressed by PR #150: backend hit `Bind for 0.0.0.0:5432 failed: port is already allocated`, frontend hit `actions/upload-artifact@v4 not supported on GHES`. PR #150 was already merged (commit `87bb20b` on `main`). Rebased `fix/tasklane-prefill-ref` onto new `main` (force-push `1a8cb06` → `1559feb`), resolved a `.ai/TODO.md` conflict by keeping both backlog item sets, kicked off CI on the rebased SHA.
+- Confirmed `CI / backend (pull_request)` is now in branch protection's required-status-checks list (added during PR #150 close-out). `CI / e2e (pull_request)` left as not-required pending one more clean PR run as the threshold.
+- Recorded the broader silent-return concern in TODO backlog: the `currentChatRef.current !== sentForChatId` guard is applied across `handleSend`, `handleTaskSubmit`, `selectChat`, `refreshFacts`, `refreshActiveFix`, and `refreshPreview`. PR #153 fixes one symptom but the same pattern can mask other drift. Either log a Sentry breadcrumb on the mismatch path or distinguish "expected stale" (chat switch) from "unexpected stale" (ref never updated) so the latter alerts.
+- First CI run on the rebased SHA passed backend and frontend but failed e2e: the new prefill regression test couldn't render the task-lane question text. Diagnosed via the job log: `POST /api/v1/ai-sessions` calls `_require_ai_enabled()` and returns 503 when no provider key is set. The e2e CI job had neither `ANTHROPIC_API_KEY` nor `GOOGLE_AI_API_KEY` in env. Locally the dev backend has a real key, hence the local pass. The Playwright `page.route` stub on `/chat` was correct but never had a chance to fire because the upstream session-creation call was 503-ing.
+- Fix: added a stub `ANTHROPIC_API_KEY: ci-stub-key-not-used-by-tests` to the e2e job env in `.gitea/workflows/ci.yml`. The Playwright stub still intercepts the actual `/chat` call in the browser, so the backend never contacts Anthropic — the gate just needs to clear. Documented the convention in a workflow comment so future AI-touching e2e tests know what to expect. Pushed `11fe32f`; CI went all-green.
+- Merged PR #153 as `68fcdc6` on `main`. Local feature branch and remote both deleted via Gitea's `delete_branch_after_merge`.
+- Opened a small follow-up `chore/post-153-handoff` PR to refresh the now-stale `.ai/` files (this entry, plus `CURRENT_TASK.md` rolling forward to "no active task — pick from `TODO.md`" and `HANDOFF.md` updating to the post-merge home position). The `data-testid` audit at the top of `TODO.md` "Up next" or the `currentChatRef` silent-return audit added in this session's backlog are the natural next pickups.
+- Files touched: `frontend/src/pages/AssistantChatPage.tsx` (the one-line fix + comment), `frontend/e2e/assistant-chat-prefill.spec.ts` (new regression test), `.gitea/workflows/ci.yml` (stub `ANTHROPIC_API_KEY` for e2e), `.ai/TODO.md` (silent-return follow-up entry, plus conflict resolution preserving PR #150's backlog additions), `.ai/CURRENT_TASK.md`, `.ai/HANDOFF.md`, `.ai/SESSION_LOG.md` (this entry).
+
+## 2026-04-25 16:41 EDT — Codex — Stabilize PR #150 e2e selectors
+
+- Investigated the remaining PR #150 failure after backend and frontend CI were green. The e2e resume smoke test was not failing because of product behavior; it used `.bg-card` plus text filtering and matched the tree filter `<select>` before the intended session card.
+- Added stable test IDs to flow session, tree, and share cards, then updated affected e2e tests to target those cards instead of Tailwind class names.
+- Hardened the CI workflow by making Postgres healthchecks authenticate as `postgres` and baking `VITE_API_URL="${PLAYWRIGHT_API_ORIGIN}"` into the e2e frontend build.
+- Verified with `git diff --check`, frontend build in Docker, no remaining `.bg-card` e2e selectors, and focused Playwright runs in an Actions-like Ubuntu container: resume spec passed, then history/library/library-start/resume/shares passed (`6 passed`).
+- Left for next session: push this WIP commit to PR #150, watch CI, merge when all three jobs are green, then enable backend branch protection and consider the e2e gate after a reliable green run.
+- Files touched: `.gitea/workflows/ci.yml`, `frontend/e2e/history.spec.ts`, `frontend/e2e/library-start.spec.ts`, `frontend/e2e/library.spec.ts`, `frontend/e2e/resume.spec.ts`, `frontend/e2e/shares.spec.ts`, `frontend/src/components/library/TreeGridView.tsx`, `frontend/src/components/library/TreeListView.tsx`, `frontend/src/pages/MySharesPage.tsx`, `frontend/src/pages/SessionHistoryPage.tsx`, `.ai/HANDOFF.md`, `.ai/CURRENT_TASK.md`, `.ai/SESSION_LOG.md`.
+
 ## 2026-04-25 12:00 America/New_York — Claude Code — Mock final AI-provider test, cache CI deps, parallelize backend with pytest-xdist
 
 - Diagnosed why CI was still red despite Codex's local 1076 passed: a single test (`test_record_decision_persists_and_bumps_state_version`) needed `ANTHROPIC_API_KEY` because the `decision: draft_template` path calls `TemplateExtractionService` → AI provider. Patched `_extract_template_parameters` with an `AsyncMock` so the test no longer depends on AI availability. Verified.

.ai/TODO.md

@@ -5,12 +5,21 @@
 
 ## Up next
 
-- [ ] **Parallelize backend pytest with pytest-xdist.** ✅ landing as PR #151. Verified locally: backend suite 22 min → 4m 28s with `-n auto` on the 8-core homelab runner. Per-worker DB isolation via `PYTEST_XDIST_WORKER` in conftest.py.
+None selected. Pick from the backlog below or `03-DEVELOPMENT-ROADMAP.md`.
 
 ## Backlog
 
-- [ ] **Frontend lint warnings cleanup.** 23 `react-hooks/exhaustive-deps` warnings remain after PR #149 (mostly missing-deps in useEffect). Either fix them or audit them for known-safe ones and add eslint-disable comments. Not blocking CI today.
+- [ ] **Frontend lint warnings cleanup.** `npm run lint` currently reports 24 warnings (0 errors): mostly `react-hooks/exhaustive-deps` plus a few unused eslint-disable directives. Either fix them or audit known-safe ones and add/remove eslint-disable comments intentionally. Not blocking CI today.
 - [ ] **Audit `filterwarnings` ignores added in `wip(handoff): restore backend suite to green`.** Codex added narrow `ResourceWarning` filters for unclosed socket/transport/event-loop noise from pytest-asyncio teardown. Worth periodically reviewing whether those are still needed (e.g. when bumping pytest-asyncio) — if a real warning appears in those forms it would be silenced.
 - [ ] **Add `data-testid` attributes to e2e-critical interactive elements.** PR #152 fixed five Playwright tests by chasing UI-text changes (`Sessions` → `Session History`, `Account Settings` → `Account Management`, `/assistant` → `/pilot`, "Flow Sessions" tab, Resume button on session cards). Each was a one-line selector update, but every UI churn re-breaks them. Adding stable `data-testid` attributes on the targeted elements (page heading wrappers, tab nav, primary action buttons) and switching tests to `getByTestId` would make these immune to copy/route renames. Scope it small — start with `SessionHistoryPage` heading, the AI/Flow Sessions tab buttons, the per-session `Resume` button, and the command-palette FlowPilot option.
 - [ ] **Per-test transactional rollback in `test_db` fixture.** Bigger engineering than xdist (which we already shipped). Instead of `DROP SCHEMA public CASCADE` per test, wrap each test in a savepoint and rollback at teardown. ~30-40% additional speedup on top of xdist for test-DB-heavy tests. Real refactor; only worth it if the suite gets significantly larger or runs more frequently.
 - [ ] **Consider `pytest-testmon` for PR-time test selection.** Tracks which tests touched which source files and only re-runs affected ones. Best for small PRs touching ~few files. Adds cache-invalidation complexity; only worth it if the suite stays painfully long even after xdist.
+- [ ] **AssistantChatPage `currentChatRef` guard is a silent return** — `handleSend`, `handleTaskSubmit`, `selectChat`, `refreshFacts`, `refreshActiveFix`, and `refreshPreview` all bail with `if (currentChatRef.current !== sentForChatId) return` when stale. This is by design for chat switching, but it also silently masked the prefill-ref bug fixed in PR #153 — the user just saw "no AI response" with no log, no toast, no Sentry event. Either (a) log a `console.warn`/Sentry breadcrumb on the mismatch path so future drift is visible, or (b) split "expected stale" (chat switch) from "unexpected stale" (ref never updated) so only the latter alerts. Pair with an audit of every `currentChatRef.current = ...` assignment vs every `setActiveChatId(...)` call to make sure they're paired everywhere.
+
+- [ ] **Allow peer-tech to escalate a colleague's session.** Today `POST /ai-sessions/{session_id}/handoff` in [endpoints/session_handoffs.py:48](backend/app/api/endpoints/session_handoffs.py#L48) filters by `AISession.user_id == current_user.id`, so only the session owner can escalate. Real MSP shops have peer hand-offs: Junior A is on lunch, Junior B sees the session is stuck and should be able to escalate it. Auth tweak: switch from session-owner check to `require_engineer_or_admin` + same-account scope. Add a `handed_off_by` audit column (already exists on `SessionHandoff`) so the original-owner-vs-actual-escalator distinction is preserved. Surfaced from /plan-eng-review on the Escalation-Mode wedge plan; v1 wedge demo doesn't need this (solo-founder pilot), but capture for v2 once 3+ pilots are live and a peer-claim need surfaces.
+
+- [ ] **Mobile/responsive design for EscalationQueue + handoff-context screen.** Pre-PMF wedge demo targets desktop only — MSP techs work on laptops/desktops in shop environments. Once 3+ paying customers exist and a tech requests mobile (likely on-call use case), spec the responsive behavior: stacked card layout below `sm:` breakpoint, full-bleed handoff-context overlay on mobile, swipe-to-claim gesture instead of Pick Up button. Surfaced from /plan-design-review on the Escalation-Mode wedge plan.
+
+- [ ] **`bg-card-hover` Tailwind class doesn't resolve.** [`frontend/src/components/layout/CommandPalette.tsx:450-451`](../frontend/src/components/layout/CommandPalette.tsx) uses `bg-card-hover` as a Tailwind utility, but Tailwind v4 generates `bg-{token}` from `--color-{token}` — and the token in [`frontend/src/index.css:15`](../frontend/src/index.css) is `--color-bg-card-hover`, which generates `bg-bg-card-hover`, not `bg-card-hover`. So those classes silently produce nothing. Other call sites (KnowledgeBaseCards, TeamSummary, ProposalBanner) use the explicit `hover:bg-[var(--color-bg-card-hover)]` form which works. Fix: change the CommandPalette classes to the explicit-var form, OR add a `--color-card-hover` semantic mapping in index.css alongside `--color-card`. Surfaced 2026-05-01 during impeccable polish sweep.
+
+- [ ] **`ConcludeSessionModal` paused/escalated step forces single-artifact choice — should allow multi-select.** [`frontend/src/components/assistant/ConcludeSessionModal.tsx`](../frontend/src/components/assistant/ConcludeSessionModal.tsx) ~lines 430-474 ("Paused/Escalated: status update options"). Today the engineer clicks ONE of Ticket Notes / Client Update / Email Draft, the buttons disappear, and the result replaces them. Real MSP escalations almost always need at least two: technical notes for the next engineer's PSA AND a non-technical client update. Same for pause (client update + ticket notes for context when resuming). Recommended shape: multi-select with smart defaults — three checkboxes (`☑ Ticket Notes  ☑ Client Update  ☐ Email Draft`); for `escalated` pre-check Ticket Notes + Client Update; for `paused` pre-check Client Update only. One "Generate" button fires all selected in parallel via existing `aiSessionsApi.generateStatusUpdate(...)` (already supports the three `audience` values: `ticket_notes`, `client_update`, `email_draft`). Each result renders in its own card with its own Copy / Post-to-PSA / Send-Email action. Surfaced 2026-05-01. Feature work, not polish — touches streaming wiring for parallel calls.

.gitea/workflows/ci.yml

@@ -23,7 +23,7 @@ jobs:
         # would race — two backend/e2e jobs both binding 0.0.0.0:5432 → the
         # second fails with "port is already allocated".
         options: >-
-          --health-cmd pg_isready
+          --health-cmd "pg_isready -U postgres"
           --health-interval 10s
           --health-timeout 5s
           --health-retries 5
@@ -125,15 +125,14 @@ jobs:
       - name: Build
         run: cd frontend && NODE_OPTIONS="--max-old-space-size=4096" npm run build
 
-      - name: Upload build artifact
-        uses: actions/upload-artifact@v3
-        with:
-          name: frontend-dist
-          path: frontend/dist
-          retention-days: 1
+      # Build artifact intentionally NOT uploaded. The e2e job below builds
+      # its own frontend rather than downloading one from this job, so there
+      # is no need for the cross-job artifact handoff (which previously broke
+      # on actions/upload-artifact@v4 GHES support and forced a v3 pin).
+      # Decoupling also lets e2e start immediately rather than waiting for
+      # this job to finish — important on a multi-runner setup.
 
   e2e:
-    needs: [frontend]
     runs-on: ubuntu-latest
 
     services:
@@ -149,7 +148,7 @@ jobs:
         # would race — two backend/e2e jobs both binding 0.0.0.0:5432 → the
         # second fails with "port is already allocated".
         options: >-
-          --health-cmd pg_isready
+          --health-cmd "pg_isready -U postgres"
           --health-interval 10s
           --health-timeout 5s
           --health-retries 5
@@ -162,6 +161,12 @@ jobs:
       PLAYWRIGHT_SECRET_KEY: ci-playwright-secret-key
       PLAYWRIGHT_TEST_EMAIL: teamadmin@resolutionflow.example.com
       PLAYWRIGHT_TEST_PASSWORD: TestPass123!
+      # AI-touching endpoints (POST /ai-sessions, /chat, /respond, etc.) are
+      # gated by `_require_ai_enabled()`, which returns 503 when no provider
+      # key is set. Tests that exercise those flows stub the AI calls in the
+      # browser via `page.route`, so the backend never actually contacts
+      # Anthropic — but the gate still has to pass. A stub value is enough.
+      ANTHROPIC_API_KEY: ci-stub-key-not-used-by-tests
 
     steps:
       - uses: actions/checkout@v4
@@ -188,11 +193,13 @@ jobs:
       - name: Install frontend dependencies
         run: cd frontend && npm ci
 
-      - name: Download frontend build
-        uses: actions/download-artifact@v3
-        with:
-          name: frontend-dist
-          path: frontend/dist
+      - name: Build frontend
+        # Building inline (instead of downloading an artifact from the
+        # frontend job) drops the cross-job dependency, so e2e can start
+        # immediately on a free runner. Adds ~1-2 min of build time, but
+        # eliminates the artifact-upload mechanism entirely (no more
+        # v3/v4 GHES headaches) and saves ~5 min of waiting.
+        run: cd frontend && NODE_OPTIONS="--max-old-space-size=4096" VITE_API_URL="${PLAYWRIGHT_API_ORIGIN}" npm run build
 
       - name: Install Playwright browser
         run: cd frontend && npx playwright install --with-deps chromium

AGENTS.md

@@ -40,7 +40,7 @@ Prefer correct architecture over minimal diff. Flag "simpler approach" tradeoffs
 ### Tooling you do NOT have
 
 - **No GitNexus tools.** Use `grep -r`, `rg`, `git grep`, or `find` for code search. For blast-radius reasoning, grep call sites manually and read the files.
-- **No gstack slash commands** (`/review`, `/ship`, `/qa`, `/browse`, `/investigate`, `/design-review`, `/plan-*`). Run the equivalent work directly: `pytest` for tests, `npm run build` for frontend validation, manual PR description for review flow.
+- **No gstack slash commands** (`/review`, `/ship`, `/qa`, `/browse`, `/investigate`, `/design-review`, `/plan-*`). Run the equivalent work directly: `pytest` for tests, `npm run build` for frontend validation, manual PR description for review flow. If `python`/`npm` aren't on PATH, the host runs services in Docker — use the `docker exec resolutionflow_{backend,frontend} …` form documented in `.ai/PROJECT_CONTEXT.md` rather than installing toolchains.
 - **No `/codex` second-opinion command.** You are Codex.
 
 ### Git trailer

CHANGELOG.md

@@ -28,7 +28,14 @@ All notable changes to ResolutionFlow are documented here.
 
 ## [Unreleased]
 
+### Changed
+- **In-product User Guides rewrite** — replaced 15 feature-dump guides with 43 problem-oriented Diátaxis how-tos grouped under 10 categories (Getting started, Working a pilot session, Closing out a session, Documentation & sharing, Authoring flows, Reusable assets, AI assistance, PSA integrations, Account & team admin, Analytics). Dropped three deprecated guides (Maintenance Flows, AI Assistant page, Flow Assist sparkle button — UI no longer exists). Renamed Step Library → Solutions Library to match canonical product terminology. Corrected sidebar entry-path references throughout (Dashboard → Home, All Flows → Flows, Sessions → History, Analytics → Data, etc.). Added `category` and optional `relatedSlugs` to the Guide schema; `GuidesHubPage` now renders category sections; `GuideDetailPage` shows a "Related guides" footer when set. Authored 14 net-new how-tos covering FlowPilot-era surfaces with no prior coverage: tasklane keyboard flow, what-we-know panel, ask-the-AI mid-session, pause-and-leave, resolve a session, record a suggested-fix outcome, escalate (Escalation Mode), post docs to a ConnectWise ticket, share a client update mid-session, build a script with Script Builder, open an AI-suggested flow, pin a flow, and invite a teammate. Fixed a long-standing rendering bug where `**bold**` markdown in `step.tip` rendered literally instead of bolded — the same regex replacement now runs on tips as on instructions. Killed the misleading "N sections" subtitle on guide cards (single-section how-tos make the count noise).
+
 ### Added
+- **TaskLane keyboard-first answer flow** (#158) — Enter submits and auto-advances to the next pending task; Shift+Enter inserts a newline; Esc cancels; after the last task, focus jumps to the Send Responses button so the engineer can fire the whole batch with one more keystroke. Mouse path also auto-advances. Subtle hint row (`⏎ submit · ⇧⏎ newline`) under each open input teaches the shortcut.
+- **Collapsible "What we know" section** (#158) — TaskLane's facts list is now a collapsible section with per-session memory in `sessionStorage`. Auto-collapses on first render at ≥5 facts so Questions and Diagnostic Checks stay above the fold; engineer's explicit toggle always wins.
+- **Escalation Mode wedge** (#155) — when an engineer escalates, the senior tech who claims the session lands on a magic-moment handoff-context screen with the structured briefing visible in seconds (no scrolling, no chat re-read). Live SSE pushes new arrivals to anyone watching the queue, atomic claim resolves race conditions, the queue auto-excludes the claimed session, the claiming user retains chat ownership for AI briefings, and a new analytics endpoint tracks post-claim time-to-first-action so you can see real minutes recovered (paired with a manual baseline — see CURRENT_TASK.md two-metric framing).
+- **Suggested-fix "Awaiting verification" outcome** (#156) — when a fix needs external confirmation (client power-cycle, AD replication, license sync) you can park it in `applied_pending` instead of forcing a worked / didn't / partial verdict. The new PendingBanner shows the parked status with worked / didn't / update reason / dismiss actions. The "Still checking" nudge records pending with a reason instead of just silencing. Page-level Resolve auto-patches pending → success before the resolution flow opens; page-level Escalate intercepts pending the same way it intercepts verifying/partial. Resolution notes and escalation packages frame the pending state honestly (provisional fix; leading hypothesis with what's being waited on).
 - Tree Templates + Import/Export marketplace (#66)
 - Recurring Issue Detection — client-specific pattern alerts (#60)
 - Step Feedback Flag — "This Step is Wrong" reporting (#58)
@@ -42,6 +49,8 @@ All notable changes to ResolutionFlow are documented here.
 - **Image support in Assistant Chat** — paste/attach images in chat input, uploaded to S3, resized for vision model, displayed in conversation history
 
 ### Changed
+- **Assistant Chat session screen — UX overhaul** (#158, "impeccable" pass) — removed the duplicate "Suggested checks" chip strip in favor of the TaskLane as the single source of truth; added an inline `Next steps · N pending` cue above the latest action-bearing AI bubble; consolidated the session header to two visible primary actions (Resolve + Escalate) plus a kebab for Context / New Ticket / Update Ticket / Pause; centered the messages column to `max-w-3xl` to match the composer; unified chat-bubble radii to `rounded-xl`; dropped every banned decoration (3px side stripes, gradient surfaces, accent borderTop, backdrop blur, pulse rings, bordered avatar boxes) for a single decoration channel per surface; unified 14 distinct text sizes into a 5-step scale (10/11/12/13/14px); split the ambiguous `MessageCircleQuestion` icon into `Pencil` (write affordance for question Answer CTA) and `HelpCircle` (universal help icon for the per-check explainer); audited and dropped redundant `font-sans` classes across the screen.
+- **Suggested-fix banner ↔ script panel are now linked** (#158) — collapsing the ProposalBanner now also hides the InlineNoTemplateDialog / TemplateMatchPanel; dismissing the banner closes both surfaces. Recording any outcome on a fix (Dismiss, It worked, Didn't work, Mark partial, Waiting to verify) closes the script panel alongside the banner state transition.
 - **Edit Procedure page** — layout overhaul and color system refinements for better visual hierarchy
 - **Flows sidebar navigation** — collapsed to reduce visual noise; session recovery removed from library view
 - **Account settings page** — audit fixes for improved consistency and usability
@@ -52,6 +61,7 @@ All notable changes to ResolutionFlow are documented here.
 - **Tenant data boundaries** — all session and tree endpoints now return 404 (not 403) for cross-tenant access attempts to avoid confirming resource existence
 
 ### Fixed
+- **`ParameterizationPreview` over-highlight on short parameter values** (#158) — the tokenizer matched highlight values via raw substring with no word-boundary check, so a single-char value like `"D"` (a drive letter) lit up every capital D in identifiers like `Get-ADUser`, `Add-Type`, `Disable-`. Added a word-boundary guard that's conditional on whether the value itself starts/ends with a word character, so values with leading/trailing punctuation (e.g. `"D:\\Folder"`) still match cleanly when adjacent to whitespace.
 - **CRITICAL: Copilot tree query isolation** (#131) — user could access any tree UUID if known, exposing full tree structure to AI. Now scoped to current account with 404 for inaccessible trees.
 - **AI session search isolation** — search endpoint leaked other users' sessions via OR(user_id, account_id). Now restricted to current user only.
 - **Analytics endpoint isolation** — GET `/analytics/flows/{tree_id}` exposed session counts for any tree UUID. Now returns 404 if tree doesn't belong to requesting account.

CURRENT-STATE.md

@@ -2,7 +2,7 @@
 
 > **Purpose:** Quick-reference file showing exactly where the project stands.
 > **For Claude Code:** Read this first to understand what's done and what's next.
-> **Last Updated:** April 12, 2026
+> **Last Updated:** May 1, 2026
 
 ---
 
@@ -10,6 +10,14 @@
 
 ---
 
+## Recently shipped (post-0.1.0.0)
+
+- **2026-05-01 — PR #158** Session-screen UX impeccable pass + tasklane keyboard flow. Heuristic score 24/40 → 33/40 across five sub-passes (distill, quieter, layout, typeset, polish). Removed duplicate "Suggested checks" chip strip → TaskLane is the single source of truth; added inline `Next steps · N pending` cue on the latest action-bearing AI bubble; consolidated session header to Resolve + Escalate + ⋯ kebab; centered messages column to match composer; dropped all banned decorations (side stripes, gradient surfaces, backdrop blur, accent borderTop) for a single decoration channel per surface; unified 14 text sizes into a 5-step scale. TaskLane keyboard flow: Enter submits + auto-advances, Shift+Enter newline, Esc cancel, focus jumps to Send after the last task. Banner ↔ script-panel are now linked (collapse hides both, any outcome closes both). WhatWeKnow section is collapsible with `sessionStorage` memory + auto-collapse-at-5-facts. Side fix: ParameterizationPreview no longer over-highlights short parameter values (word-boundary check). Two backlog entries logged in `.ai/TODO.md`: ConcludeSessionModal multi-select and `bg-card-hover` Tailwind drift in CommandPalette.
+- **2026-05-01 — PR #156** Suggested-fix "Awaiting verification" outcome. Engineers can now park a fix in `applied_pending` (waiting on client power-cycle, AD replication, license sync, etc.) instead of forcing a synchronous worked/didn't/partial verdict. PendingBanner with worked / didn't / update reason / dismiss; nudge "Still checking" records pending with a reason; page-level Resolve auto-patches pending → success before the resolution flow opens; page-level Escalate intercepts pending. Migration `c0f3a4b7e91d` (`pending_reason` column + status CHECK constraint).
+- **2026-04-30 — PR #155** Escalation Mode wedge. Magic-moment handoff-context screen for senior pickup, live SSE escalation arrivals, post-claim time-to-first-action metric (`GET /analytics/flowpilot/escalations`), atomic role-gated claim with conflict resolution, queue self-exclusion, chat ownership extended to claimed sessions. The wedge for the first paying-customer push.
+
+---
+
 ## What's Complete
 
 ### Core Platform

backend/alembic/versions/2aa73d3231c2_account_invites_add_revoked_at_and_.py

@@ -0,0 +1,30 @@
+"""account_invites add revoked_at and email_sent_at
+
+Revision ID: 2aa73d3231c2
+Revises: e1af7ab57ceb
+Create Date: 2026-05-06 07:28:28.514384
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = '2aa73d3231c2'
+down_revision: Union[str, None] = 'e1af7ab57ceb'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column("account_invites", sa.Column("revoked_at", sa.DateTime(timezone=True), nullable=True))
+    op.add_column("account_invites", sa.Column("email_sent_at", sa.DateTime(timezone=True), nullable=True))
+    op.create_index("ix_account_invites_revoked_at", "account_invites", ["revoked_at"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_account_invites_revoked_at", table_name="account_invites")
+    op.drop_column("account_invites", "email_sent_at")
+    op.drop_column("account_invites", "revoked_at")

backend/alembic/versions/58e3caaa6269_users_add_role_at_signup_and_onboarding_.py

@@ -0,0 +1,28 @@
+"""users add role_at_signup and onboarding_step_completed
+
+Revision ID: 58e3caaa6269
+Revises: 5bb055a1593e
+Create Date: 2026-05-06 07:25:16.780761
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = '58e3caaa6269'
+down_revision: Union[str, None] = '5bb055a1593e'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column("users", sa.Column("role_at_signup", sa.String(50), nullable=True))
+    op.add_column("users", sa.Column("onboarding_step_completed", sa.Integer(), nullable=True))
+
+
+def downgrade() -> None:
+    op.drop_column("users", "onboarding_step_completed")
+    op.drop_column("users", "role_at_signup")

backend/alembic/versions/5bb055a1593e_users_password_hash_nullable.py

@@ -0,0 +1,47 @@
+"""users password_hash nullable
+
+Revision ID: 5bb055a1593e
+Revises: b1fad5ddf357
+Create Date: 2026-05-06 07:23:21.480252
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = '5bb055a1593e'
+down_revision: Union[str, None] = 'b1fad5ddf357'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.alter_column(
+        "users",
+        "password_hash",
+        existing_type=sa.String(255),
+        nullable=True,
+    )
+
+
+def downgrade() -> None:
+    # NOTE: downgrade is non-trivial if any OAuth-only users exist.
+    # This downgrade fails fast in that case rather than corrupting data.
+    conn = op.get_bind()
+    null_count = conn.execute(
+        sa.text("SELECT COUNT(*) FROM users WHERE password_hash IS NULL")
+    ).scalar()
+    if null_count and null_count > 0:
+        raise RuntimeError(
+            f"Cannot downgrade: {null_count} OAuth-only users have NULL password_hash. "
+            "Set passwords or delete those rows before downgrading."
+        )
+    op.alter_column(
+        "users",
+        "password_hash",
+        existing_type=sa.String(255),
+        nullable=False,
+    )

backend/alembic/versions/71efd2102f49_add_pending_status_to_suggested_fixes.py

@@ -0,0 +1,60 @@
+"""add applied_pending status + pending_reason to session_suggested_fixes
+
+Adds the `applied_pending` non-terminal status (engineer ran the fix but
+verification is deferred — waiting on client, async sync, etc) alongside
+the existing `applied_partial` status. Mirrors partial_notes with a new
+pending_reason column for the "what are you waiting on?" prose.
+
+Revision ID: c0f3a4b7e91d
+Revises: 71efd2102f49
+Create Date: 2026-04-30
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+revision: str = "c0f3a4b7e91d"
+down_revision: Union[str, None] = "71efd2102f49"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "session_suggested_fixes",
+        sa.Column("pending_reason", sa.Text(), nullable=True),
+    )
+    op.drop_constraint(
+        "ck_session_suggested_fixes_status",
+        "session_suggested_fixes",
+        type_="check",
+    )
+    op.create_check_constraint(
+        "ck_session_suggested_fixes_status",
+        "session_suggested_fixes",
+        "status IN ('proposed', 'applied_success', 'applied_failed', "
+        "'applied_partial', 'applied_pending', 'dismissed')",
+    )
+
+
+def downgrade() -> None:
+    op.execute(
+        "UPDATE session_suggested_fixes "
+        "SET status = 'applied_partial', "
+        "    partial_notes = COALESCE(partial_notes, pending_reason) "
+        "WHERE status = 'applied_pending'"
+    )
+    op.drop_constraint(
+        "ck_session_suggested_fixes_status",
+        "session_suggested_fixes",
+        type_="check",
+    )
+    op.create_check_constraint(
+        "ck_session_suggested_fixes_status",
+        "session_suggested_fixes",
+        "status IN ('proposed', 'applied_success', 'applied_failed', "
+        "'applied_partial', 'dismissed')",
+    )
+    op.drop_column("session_suggested_fixes", "pending_reason")

backend/alembic/versions/b1fad5ddf357_add_oauth_identities.py

@@ -0,0 +1,39 @@
+"""add oauth_identities
+
+Revision ID: b1fad5ddf357
+Revises: c0f3a4b7e91d
+Create Date: 2026-05-06 07:17:11.374555
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import UUID
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'b1fad5ddf357'
+down_revision: Union[str, None] = 'c0f3a4b7e91d'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "oauth_identities",
+        sa.Column("id", UUID(as_uuid=True), primary_key=True),
+        sa.Column("user_id", UUID(as_uuid=True), sa.ForeignKey("users.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("provider", sa.String(20), nullable=False),
+        sa.Column("provider_subject", sa.String(255), nullable=False),
+        sa.Column("provider_email_at_link", sa.String(255), nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.func.now()),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.func.now()),
+        sa.UniqueConstraint("provider", "provider_subject", name="uq_oauth_identities_provider_subject"),
+    )
+    op.create_index("ix_oauth_identities_user_id", "oauth_identities", ["user_id"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_oauth_identities_user_id", table_name="oauth_identities")
+    op.drop_table("oauth_identities")

backend/alembic/versions/c6cbfc534fad_subscriptions_pilot_complimentary_.py

@@ -0,0 +1,47 @@
+"""subscriptions pilot complimentary backfill
+
+This migration converts existing pilot/dev accounts to permanent complimentary
+Pro per the self-serve signup spec section 5. Forward-only; downgrade is
+prohibited because original status is not preserved.
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+revision: str = "c6cbfc534fad"
+down_revision: Union[str, None] = "c982a3fc4bf1"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Set status='complimentary' and plan='pro' for all existing accounts that
+    don't have a canceled or past_due subscription. Pilot users transition to
+    permanent complimentary Pro per spec section 5.
+
+    Forward-only — does not preserve original status values."""
+    conn = op.get_bind()
+    # Update existing rows
+    conn.execute(sa.text("""
+        UPDATE subscriptions
+        SET status = 'complimentary', plan = 'pro',
+            current_period_end = NULL, current_period_start = NULL,
+            updated_at = now()
+        WHERE status NOT IN ('canceled', 'past_due')
+    """))
+    # Backfill: any account without a Subscription row gets one
+    conn.execute(sa.text("""
+        INSERT INTO subscriptions (id, account_id, plan, status, cancel_at_period_end, created_at, updated_at)
+        SELECT gen_random_uuid(), a.id, 'pro', 'complimentary', false, now(), now()
+        FROM accounts a
+        WHERE NOT EXISTS (SELECT 1 FROM subscriptions s WHERE s.account_id = a.id)
+    """))
+
+
+def downgrade() -> None:
+    raise RuntimeError(
+        "Cannot downgrade: original subscription state is not preserved. "
+        "Restore from backup if needed."
+    )

backend/alembic/versions/c982a3fc4bf1_add_stripe_events.py

@@ -0,0 +1,45 @@
+"""add stripe_events
+
+Revision ID: c982a3fc4bf1
+Revises: f7da3f93b519
+Create Date: 2026-05-06 07:32:08.027633
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import JSONB
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'c982a3fc4bf1'
+down_revision: Union[str, None] = 'f7da3f93b519'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "stripe_events",
+        sa.Column("id", sa.String(length=255), primary_key=True, nullable=False),
+        sa.Column("event_type", sa.String(length=100), nullable=False),
+        sa.Column(
+            "processed_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.func.now(),
+        ),
+        sa.Column(
+            "payload_excerpt",
+            JSONB,
+            nullable=False,
+            server_default=sa.text("'{}'::jsonb"),
+        ),
+    )
+    op.create_index("ix_stripe_events_event_type", "stripe_events", ["event_type"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_stripe_events_event_type", table_name="stripe_events")
+    op.drop_table("stripe_events")

backend/alembic/versions/e1af7ab57ceb_accounts_add_wizard_columns.py

@@ -0,0 +1,28 @@
+"""accounts add wizard columns
+
+Revision ID: e1af7ab57ceb
+Revises: 58e3caaa6269
+Create Date: 2026-05-06 07:27:15.755518
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'e1af7ab57ceb'
+down_revision: Union[str, None] = '58e3caaa6269'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column("accounts", sa.Column("team_size_bucket", sa.String(20), nullable=True))
+    op.add_column("accounts", sa.Column("primary_psa", sa.String(20), nullable=True))
+
+
+def downgrade() -> None:
+    op.drop_column("accounts", "primary_psa")
+    op.drop_column("accounts", "team_size_bucket")

backend/alembic/versions/f236a91224d0_add_plan_billing.py

@@ -0,0 +1,41 @@
+"""add plan_billing
+
+Revision ID: f236a91224d0
+Revises: 2aa73d3231c2
+Create Date: 2026-05-06 07:30:06.807887
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'f236a91224d0'
+down_revision: Union[str, None] = '2aa73d3231c2'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "plan_billing",
+        sa.Column("plan", sa.String(50), sa.ForeignKey("plan_limits.plan"), primary_key=True),
+        sa.Column("display_name", sa.String(255), nullable=False),
+        sa.Column("description", sa.Text(), nullable=True),
+        sa.Column("monthly_price_cents", sa.Integer(), nullable=True),
+        sa.Column("annual_price_cents", sa.Integer(), nullable=True),
+        sa.Column("stripe_product_id", sa.String(255), nullable=True),
+        sa.Column("stripe_monthly_price_id", sa.String(255), nullable=True),
+        sa.Column("stripe_annual_price_id", sa.String(255), nullable=True),
+        sa.Column("is_public", sa.Boolean(), nullable=False, server_default=sa.text("true")),
+        sa.Column("is_archived", sa.Boolean(), nullable=False, server_default=sa.text("false")),
+        sa.Column("sort_order", sa.Integer(), nullable=False, server_default=sa.text("0")),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.func.now()),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.func.now()),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("plan_billing")

backend/alembic/versions/f7da3f93b519_add_sales_leads.py

@@ -0,0 +1,57 @@
+"""add sales_leads
+
+Revision ID: f7da3f93b519
+Revises: f236a91224d0
+Create Date: 2026-05-06 07:31:39.533305
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import UUID
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'f7da3f93b519'
+down_revision: Union[str, None] = 'f236a91224d0'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "sales_leads",
+        sa.Column("id", UUID(as_uuid=True), primary_key=True, nullable=False),
+        sa.Column("email", sa.String(length=255), nullable=False),
+        sa.Column("name", sa.String(length=255), nullable=False),
+        sa.Column("company", sa.String(length=255), nullable=False),
+        sa.Column("team_size", sa.String(length=20), nullable=True),
+        sa.Column("message", sa.Text(), nullable=True),
+        sa.Column("source", sa.String(length=50), nullable=False),
+        sa.Column("posthog_distinct_id", sa.String(length=255), nullable=True),
+        sa.Column(
+            "status",
+            sa.String(length=20),
+            nullable=False,
+            server_default=sa.text("'new'"),
+        ),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.func.now(),
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.func.now(),
+        ),
+    )
+    op.create_index("ix_sales_leads_email", "sales_leads", ["email"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_sales_leads_email", table_name="sales_leads")
+    op.drop_table("sales_leads")

backend/app/api/deps.py

@@ -83,11 +83,12 @@ async def get_current_active_user(
     current_user: Annotated[User, Depends(get_current_user)],
     db: Annotated[AsyncSession, Depends(get_admin_db)],
 ) -> User:
-    """Ensure user is active (not disabled). Auto-downgrades expired trials.
-    Enforces must_change_password — blocks all routes except allowlist.
+    """Ensure user is active (not disabled). Enforces must_change_password —
+    blocks all routes except allowlist.
 
-    Uses get_admin_db: runs before require_tenant_context sets the ContextVar,
-    so tenant-scoped tables (subscriptions) would return 0 rows via app role.
+    Trial expiry enforcement now happens via require_active_subscription in
+    individual routers, NOT here. This dep no longer mutates Subscription
+    state.
     """
     if not current_user.is_active:
         raise HTTPException(
@@ -106,26 +107,6 @@ async def get_current_active_user(
     # Set Sentry user context for error attribution
     sentry_sdk.set_user({"id": str(current_user.id), "email": current_user.email})
 
-    # Lightweight trial expiry check
-    if current_user.account_id:
-        from app.models.subscription import Subscription
-        from datetime import datetime, timezone
-        result = await db.execute(
-            select(Subscription).where(Subscription.account_id == current_user.account_id)
-        )
-        subscription = result.scalar_one_or_none()
-        if (
-            subscription
-            and subscription.status == "trialing"
-            and subscription.current_period_end
-            and subscription.current_period_end < datetime.now(timezone.utc)
-        ):
-            subscription.plan = "free"
-            subscription.status = "active"
-            subscription.current_period_end = None
-            subscription.current_period_start = None
-            await db.commit()
-
     return current_user
 
 
@@ -241,3 +222,114 @@ async def require_admin_db(
     the user object is needed in the handler.
     """
     return db
+
+
+_SUBSCRIPTION_GUARD_ALLOWLIST = {
+    "/api/v1/auth/me",
+    "/api/v1/auth/logout",
+    "/api/v1/auth/password/change",
+    "/api/v1/auth/email/send-verification",
+    "/api/v1/auth/email/verify",
+    "/api/v1/billing/state",
+    "/api/v1/billing/checkout-session",
+    "/api/v1/billing/portal-session",
+    "/api/v1/users/me",
+    "/api/v1/users/me/onboarding-step",
+}
+
+
+async def require_active_subscription(
+    request: Request,
+    current_user: Annotated[User, Depends(get_current_active_user)],
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
+):
+    """Returns the Subscription row when the account has access; raises 402
+    when locked. Mounted on routers requiring Pro entitlement.
+
+    'Locked' = (trialing AND current_period_end < now()) OR
+              (canceled OR incomplete OR no subscription).
+    Active states: active, complimentary, trialing-with-time-remaining, past_due.
+    """
+    if request.url.path in _SUBSCRIPTION_GUARD_ALLOWLIST:
+        return None
+
+    from app.models.subscription import Subscription
+    from datetime import datetime, timezone
+
+    result = await db.execute(
+        select(Subscription).where(Subscription.account_id == current_user.account_id)
+    )
+    sub = result.scalar_one_or_none()
+
+    if sub is None:
+        raise HTTPException(
+            status_code=402,
+            detail={"error": "no_subscription", "upgrade_url": "/account/billing/select-plan"},
+        )
+
+    now = datetime.now(timezone.utc)
+    is_live = (
+        sub.status in ("active", "complimentary", "past_due")
+        or (
+            sub.status == "trialing"
+            and sub.current_period_end is not None
+            and sub.current_period_end > now
+        )
+    )
+    if not is_live:
+        raise HTTPException(
+            status_code=402,
+            detail={
+                "error": "subscription_inactive",
+                "status": sub.status,
+                "plan": sub.plan,
+                "current_period_end": sub.current_period_end.isoformat() if sub.current_period_end else None,
+                "upgrade_url": "/account/billing/select-plan",
+            },
+        )
+
+    return sub
+
+
+_EMAIL_VERIFICATION_ALLOWLIST = {
+    "/api/v1/auth/me",
+    "/api/v1/auth/logout",
+    "/api/v1/auth/email/send-verification",
+    "/api/v1/auth/email/verify",
+    "/api/v1/auth/password/change",
+    "/api/v1/users/me",
+    "/api/v1/billing/state",
+    "/api/v1/billing/checkout-session",
+    "/api/v1/billing/portal-session",
+}
+
+VERIFICATION_GRACE_DAYS = 7
+
+
+async def require_verified_email_after_grace(
+    request: Request,
+    current_user: Annotated[User, Depends(get_current_active_user)],
+):
+    """Enforces 'this user has verified email OR is still in 7-day grace.'
+    OAuth signups bypass cleanly because /auth/{google,microsoft}/callback
+    sets users.email_verified_at = now() (provider-attested)."""
+    from datetime import datetime, timezone, timedelta
+
+    if request.url.path in _EMAIL_VERIFICATION_ALLOWLIST:
+        return
+
+    if current_user.email_verified_at is not None:
+        return
+
+    grace_ends = current_user.created_at + timedelta(days=VERIFICATION_GRACE_DAYS)
+    if datetime.now(timezone.utc) < grace_ends:
+        return
+
+    raise HTTPException(
+        status_code=403,
+        detail={
+            "error": "email_not_verified",
+            "grace_ended_at": grace_ends.isoformat(),
+            "resend_url": "/api/v1/auth/email/send-verification",
+        },
+    )

backend/app/api/endpoints/accounts.py

@@ -19,7 +19,7 @@ from app.models.account_invite import AccountInvite
 from app.models.account_settings import AccountSettings
 from app.models.subscription import Subscription
 from app.models.user import User
-from app.schemas.account import AccountResponse, AccountUpdate, AccountInviteCreate, AccountInviteResponse, TransferOwnershipRequest
+from app.schemas.account import AccountResponse, AccountUpdate, AccountInviteCreate, AccountInviteResponse, AccountInviteBulkCreate, AccountInviteBulkResponse, TransferOwnershipRequest
 from app.schemas.subscription import SubscriptionResponse, PlanLimitsResponse, UsageResponse, SubscriptionDetails
 from app.schemas.user import UserResponse, AccountRoleUpdate
 from app.core.security import verify_password
@@ -260,7 +260,7 @@ async def create_invite(
     db: Annotated[AsyncSession, Depends(get_db)],
     current_user: Annotated[User, Depends(require_account_owner)]
 ):
-    """Create an invite to join this account (owner only)."""
+    """Create an invite to join this account (owner only). Sends invite email."""
     code = secrets.token_urlsafe(16)
 
     expires_at = None
@@ -276,11 +276,109 @@ async def create_invite(
         expires_at=expires_at,
     )
     db.add(invite)
+    await db.flush()
+
+    # Lookup account name for email
+    account_result = await db.execute(
+        select(Account).where(Account.id == current_user.account_id)
+    )
+    account = account_result.scalar_one()
+
+    # Send invite email — non-blocking on failure (function returns False on error)
+    email_sent = await EmailService.send_account_invite_email(
+        to_email=invite.email,
+        code=code,
+        account_name=account.name,
+        role=invite.role,
+    )
+    if email_sent:
+        invite.email_sent_at = datetime.now(timezone.utc)
+
     await db.commit()
     await db.refresh(invite)
     return invite
 
 
+@router.post("/me/invites/bulk", response_model=AccountInviteBulkResponse, status_code=status.HTTP_201_CREATED)
+async def create_invites_bulk(
+    payload: AccountInviteBulkCreate,
+    db: Annotated[AsyncSession, Depends(get_db)],
+    current_user: Annotated[User, Depends(require_account_owner)]
+):
+    """Create multiple invites in one call (wizard step 3 supports up to N).
+    Per-row failures are returned in `failed`; successes in `created`."""
+    # Lookup account once for email rendering
+    account_result = await db.execute(
+        select(Account).where(Account.id == current_user.account_id)
+    )
+    account = account_result.scalar_one()
+
+    created: list[AccountInvite] = []
+    failed: list[dict] = []
+    for invite_data in payload.invites:
+        try:
+            code = secrets.token_urlsafe(16)
+            expires_at = None
+            if invite_data.expires_in_days:
+                expires_at = datetime.now(timezone.utc) + timedelta(days=invite_data.expires_in_days)
+
+            invite = AccountInvite(
+                account_id=current_user.account_id,
+                invited_by_id=current_user.id,
+                email=invite_data.email,
+                code=code,
+                role=invite_data.role,
+                expires_at=expires_at,
+            )
+            db.add(invite)
+            await db.flush()
+
+            email_sent = await EmailService.send_account_invite_email(
+                to_email=invite.email,
+                code=code,
+                account_name=account.name,
+                role=invite.role,
+            )
+            if email_sent:
+                invite.email_sent_at = datetime.now(timezone.utc)
+
+            created.append(invite)
+        except Exception as e:
+            failed.append({"email": invite_data.email, "error": str(e)})
+
+    await db.commit()
+    for inv in created:
+        await db.refresh(inv)
+
+    return AccountInviteBulkResponse(created=created, failed=failed)
+
+
+@router.delete("/me/invites/{invite_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def revoke_invite(
+    invite_id: UUID,
+    db: Annotated[AsyncSession, Depends(get_db)],
+    current_user: Annotated[User, Depends(require_account_owner)]
+):
+    """Soft-revoke an invitation by setting revoked_at. Idempotent on already-
+    revoked invites; rejects already-accepted invites."""
+    result = await db.execute(
+        select(AccountInvite).where(
+            AccountInvite.id == invite_id,
+            AccountInvite.account_id == current_user.account_id,
+        )
+    )
+    invite = result.scalar_one_or_none()
+    if not invite:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Invite not found")
+    if invite.is_revoked:
+        return None  # idempotent
+    if invite.is_used:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Cannot revoke an accepted invite")
+    invite.revoked_at = datetime.now(timezone.utc)
+    await db.commit()
+    return None
+
+
 @router.post("/me/invites/{invite_id}/resend", response_model=AccountInviteResponse)
 async def resend_invite(
     invite_id: UUID,

backend/app/api/endpoints/ai_sessions.py

@@ -15,7 +15,7 @@ from datetime import datetime
 from typing import Annotated, Optional
 from uuid import UUID
 
-from fastapi import APIRouter, Depends, HTTPException, Query, Request, status
+from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException, Query, Request, status
 from sqlalchemy import or_, select, func, text
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm import selectinload
@@ -452,6 +452,13 @@ async def resolve_session(
 
 
 # ── Escalate ──
+#
+# Thin shim over HandoffManager. The legacy `flowpilot_engine.escalate_session`
+# is no longer the source of truth — every escalation now creates a
+# SessionHandoff row, fans out via the SSE bus, dispatches AppNotification +
+# external channels via notify(), and emails per-user. EscalateModal and the
+# /handoff endpoint both funnel through here / through HandoffManager so the
+# senior-pickup magic-moment screen works regardless of entry point.
 
 @router.post("/{session_id}/escalate", response_model=SessionCloseResponse)
 @limiter.limit("15/minute")
@@ -459,25 +466,62 @@ async def escalate_session(
     request: Request,
     session_id: UUID,
     data: EscalateSessionRequest,
+    background_tasks: BackgroundTasks,
     current_user: Annotated[User, Depends(get_current_active_user)],
     db: Annotated[AsyncSession, Depends(get_db)],
     _: None = Depends(require_engineer_or_admin),
 ):
-    """Escalate a FlowPilot session to another engineer."""
+    """Escalate a FlowPilot session — unified through HandoffManager."""
+    from app.services.handoff_manager import HandoffManager, enrich_escalation_async
+
+    # Owner-only — matches the original constraint on flowpilot_engine.escalate_session.
+    session_result = await db.execute(
+        select(AISession).where(
+            AISession.id == session_id,
+            AISession.user_id == current_user.id,
+        )
+    )
+    session = session_result.scalar_one_or_none()
+    if not session:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="Session not found"
+        )
+
+    manager = HandoffManager(db)
     try:
-        result = await flowpilot_engine.escalate_session(
+        handoff = await manager.create_handoff(
             session_id=session_id,
-            request=data,
+            intent="escalate",
+            engineer_notes=data.escalation_reason,
             user_id=current_user.id,
-            db=db,
+            priority="normal",
+            target_user_id=data.escalated_to_id,
         )
     except ValueError as e:
         raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
-    except PermissionError as e:
-        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=str(e))
+
+    documentation, psa_result = await manager.finalize_escalation(
+        handoff, session, current_user.id
+    )
 
     await db.commit()
-    return result
+
+    await manager.dispatch_escalation_notifications(handoff)
+
+    # AI enrichment (Sonnet assessment + enhanced escalation_package) runs
+    # in the background so the escalating engineer doesn't wait on
+    # 15-25s of model latency. Result lands on the handoff row when ready;
+    # the senior's magic-moment screen reads it at pickup time.
+    background_tasks.add_task(
+        enrich_escalation_async, handoff.id, current_user.id
+    )
+
+    return SessionCloseResponse(
+        session_id=session.id,
+        status=session.status,
+        documentation=documentation,
+        **psa_result,
+    )
 
 
 # ── Pause ──
@@ -644,7 +688,8 @@ async def get_escalation_queue(
         select(AISession)
         .where(
             scope_filter,
-            AISession.status == "requesting_escalation",
+            AISession.status.in_(("requesting_escalation", "escalated")),
+            AISession.user_id != current_user.id,
         )
         .order_by(AISession.created_at.desc())
     )
@@ -838,13 +883,25 @@ async def list_sessions(
     date_to: Optional[datetime] = Query(None),
     q: Optional[str] = Query(None, min_length=2, max_length=200),
 ):
-    """List the current user's AI sessions (owned or picked up)."""
+    """List the current user's AI sessions (owned or picked up).
+
+    "Picked up" includes both the legacy escalation_package.picked_up_by
+    marker (set by flowpilot_engine.pickup_session) AND the new
+    escalated_to_id field (set by HandoffManager.claim_session for the
+    unified handoff/escalate path). Without the escalated_to_id branch
+    the senior tech wouldn't see a session they just claimed in their
+    chat sidebar — the picked-up session lands as the active chat with
+    no entry in the list, which is what the user reported as "4 versions
+    of the session" (their unrelated owned sessions show up while the
+    claimed one is invisible).
+    """
     user_id_str = str(current_user.id)
     query = (
         select(AISession)
         .where(
             or_(
                 AISession.user_id == current_user.id,
+                AISession.escalated_to_id == current_user.id,
                 AISession.escalation_package["picked_up_by"].as_string() == user_id_str,
             )
         )
@@ -901,10 +958,21 @@ async def get_session(
     if not session:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Session not found")
 
-    # Allow access if user is owner, escalation target, or picked-up handler
+    # Allow access if user is owner, escalation target, or picked-up handler.
+    # Sessions in transit (requesting_escalation / escalated) are also
+    # readable by any account member — the whole point of escalation is that
+    # other techs can see the context before claiming. Tenant boundary is
+    # enforced by RLS on the underlying query, so account-scope is the right
+    # ceiling for in-transit reads.
     pkg = session.escalation_package or {}
     is_handler = pkg.get("picked_up_by") == str(current_user.id)
-    if session.user_id != current_user.id and session.escalated_to_id != current_user.id and not is_handler:
+    is_in_transit = session.status in ("requesting_escalation", "escalated")
+    if (
+        session.user_id != current_user.id
+        and session.escalated_to_id != current_user.id
+        and not is_handler
+        and not is_in_transit
+    ):
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Session not found")
 
     return _build_session_detail(session)

backend/app/api/endpoints/auth.py

@@ -1,3 +1,4 @@
+import logging
 import secrets
 import string
 from datetime import datetime, timezone, timedelta
@@ -41,6 +42,8 @@ from app.core.email import EmailService
 from app.api.deps import get_current_active_user, get_refresh_token_payload
 from app.core.audit import log_audit
 
+logger = logging.getLogger(__name__)
+
 router = APIRouter(prefix="/auth", tags=["authentication"])
 
 
@@ -62,6 +65,22 @@ def _generate_display_code() -> str:
     return ''.join(secrets.choice(chars) for _ in range(8))
 
 
+async def _reject_if_oauth_only(db: AsyncSession, user) -> None:
+    """If the user has no password_hash, raise 400 with a list of linked
+    providers so the client can redirect them to the right OAuth flow."""
+    if user is None or user.password_hash is not None:
+        return
+    from app.models.oauth_identity import OAuthIdentity
+    result = await db.execute(
+        select(OAuthIdentity.provider).where(OAuthIdentity.user_id == user.id)
+    )
+    providers = [row for row in result.scalars().all()]
+    raise HTTPException(
+        status_code=400,
+        detail={"error": "use_oauth_provider", "providers": providers},
+    )
+
+
 @router.post("/register", response_model=UserResponse, status_code=status.HTTP_201_CREATED)
 @limiter.limit("3/minute")
 async def register(
@@ -108,6 +127,12 @@ async def register(
                 detail="Account invite code has expired"
             )
 
+        if account_invite_record.email.lower() != user_data.email.lower():
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail={"error": "invite_email_mismatch"},
+            )
+
     # Validate platform invite code (skip if account invite was provided)
     invite_code_record = None
     if not account_invite_record:
@@ -195,26 +220,30 @@ async def register(
         # Now set account owner and create subscription
         new_account.owner_id = new_user.id
 
-        # Apply plan/trial from invite code if present
-        sub_plan = "free"
-        sub_status = "active"
-        period_start = None
-        period_end = None
         if invite_code_record and invite_code_record.assigned_plan:
+            # Plan/trial driven by platform invite code (existing pilot flow)
             sub_plan = invite_code_record.assigned_plan
+            sub_status = "active"
+            period_start = None
+            period_end = None
             if invite_code_record.trial_duration_days:
                 sub_status = "trialing"
                 period_start = datetime.now(timezone.utc)
                 period_end = period_start + timedelta(days=invite_code_record.trial_duration_days)
-
-        new_subscription = Subscription(
-            account_id=new_account.id,
-            plan=sub_plan,
-            status=sub_status,
-            current_period_start=period_start,
-            current_period_end=period_end,
-        )
-        db.add(new_subscription)
+            db.add(Subscription(
+                account_id=new_account.id,
+                plan=sub_plan,
+                status=sub_status,
+                current_period_start=period_start,
+                current_period_end=period_end,
+            ))
+        else:
+            # New self-serve shop — start the standard Pro trial.
+            # start_trial commits internally; flush our pending User/Account changes
+            # first so the FK is satisfied.
+            await db.flush()
+            from app.services.billing import BillingService
+            await BillingService.start_trial(db, new_account.id)
 
     # Mark platform invite code as used
     if invite_code_record:
@@ -224,6 +253,34 @@ async def register(
     await db.commit()
     await db.refresh(new_user)
 
+    # Auto-send verification email for newly-registered users.
+    # Skip silently if verification already done (shouldn't happen for fresh
+    # users, but defensive).
+    if new_user.email_verified_at is None:
+        verification_enabled = await SettingsManager.get(
+            "email_verification_enabled", db, default=True
+        )
+        if verification_enabled:
+            try:
+                raw_token = create_email_verification_token(str(new_user.id))
+                payload = decode_token(raw_token)
+                if payload and payload.get("jti"):
+                    token_record = EmailVerificationToken(
+                        token_hash=hash_token(payload["jti"]),
+                        user_id=new_user.id,
+                        expires_at=datetime.fromtimestamp(payload["exp"], tz=timezone.utc),
+                    )
+                    db.add(token_record)
+                    await db.commit()
+
+                    verification_url = f"{settings.FRONTEND_URL}/verify-email?token={raw_token}"
+                    await EmailService.send_email_verification_email(
+                        to_email=new_user.email,
+                        verification_url=verification_url,
+                    )
+            except Exception as e:
+                logger.warning("verification email send failed for %s: %s", new_user.email, e)
+
     return new_user
 
 
@@ -239,6 +296,7 @@ async def login(
     result = await db.execute(select(User).where(User.email == form_data.username))
     user = result.scalar_one_or_none()
 
+    await _reject_if_oauth_only(db, user)
     if not user or not verify_password(form_data.password, user.password_hash):
         raise HTTPException(
             status_code=status.HTTP_401_UNAUTHORIZED,
@@ -276,6 +334,7 @@ async def login_json(
     result = await db.execute(select(User).where(User.email == credentials.email))
     user = result.scalar_one_or_none()
 
+    await _reject_if_oauth_only(db, user)
     if not user or not verify_password(credentials.password, user.password_hash):
         raise HTTPException(
             status_code=status.HTTP_401_UNAUTHORIZED,
@@ -441,6 +500,7 @@ async def change_password(
     db: Annotated[AsyncSession, Depends(get_admin_db)]
 ):
     """Change the current user's password."""
+    await _reject_if_oauth_only(db, current_user)
     if not verify_password(data.current_password, current_user.password_hash):
         raise HTTPException(
             status_code=status.HTTP_401_UNAUTHORIZED,
@@ -484,7 +544,7 @@ async def forgot_password(
     result = await db.execute(select(User).where(User.email == data.email))
     user = result.scalar_one_or_none()
 
-    if user:
+    if user and user.password_hash is not None:
         # Create reset token JWT
         raw_token = create_password_reset_token(str(user.id))
         payload = decode_token(raw_token)

backend/app/api/endpoints/billing.py

@@ -0,0 +1,52 @@
+from typing import Annotated
+
+from fastapi import APIRouter, Depends
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.deps import get_current_active_user
+from app.core.admin_database import get_admin_db
+from app.core.config import settings
+from app.models.account import Account
+from app.models.user import User
+from app.schemas.billing import (
+    BillingStateResponse,
+    CheckoutSessionCreate,
+    CheckoutSessionResponse,
+)
+from app.services.billing import BillingService
+
+router = APIRouter(prefix="/billing", tags=["billing"])
+
+
+@router.post("/checkout-session", response_model=CheckoutSessionResponse)
+async def create_checkout_session(
+    payload: CheckoutSessionCreate,
+    current_user: Annotated[User, Depends(get_current_active_user)],
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
+) -> CheckoutSessionResponse:
+    account = (await db.execute(
+        select(Account).where(Account.id == current_user.account_id)
+    )).scalar_one()
+    url = await BillingService.create_checkout_session(
+        db=db,
+        account=account,
+        plan=payload.plan,
+        seats=payload.seats,
+        billing_interval=payload.billing_interval,
+        success_url=f"{settings.FRONTEND_URL}/account/billing?success=1",
+        cancel_url=f"{settings.FRONTEND_URL}/account/billing/select-plan",
+    )
+    return CheckoutSessionResponse(url=url)
+
+
+@router.get("/state", response_model=BillingStateResponse)
+async def get_billing_state(
+    current_user: Annotated[User, Depends(get_current_active_user)],
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
+) -> BillingStateResponse:
+    account = (await db.execute(
+        select(Account).where(Account.id == current_user.account_id)
+    )).scalar_one()
+    state = await BillingService.get_billing_state(db, account)
+    return BillingStateResponse(**state)

backend/app/api/endpoints/flowpilot_analytics.py

@@ -3,8 +3,10 @@
 Endpoints:
   GET /analytics/flowpilot?period=30d — Main dashboard data
   GET /analytics/flowpilot/knowledge-gaps — Knowledge gap report
+  GET /analytics/flowpilot/escalations?period=30d — Escalation handoff metrics
 """
 import logging
+import statistics
 from datetime import datetime, timezone, timedelta
 from typing import Annotated, Optional
 
@@ -13,10 +15,17 @@ from sqlalchemy import select, func, case, cast, Date, extract
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.core.rate_limit import limiter
-from app.api.deps import get_current_active_user, get_db, require_team_admin
+from app.api.deps import (
+    get_current_active_user,
+    get_db,
+    require_engineer_or_admin,
+    require_team_admin,
+)
 from app.models.user import User
 from app.models.tree import Tree
 from app.models.ai_session import AISession
+from app.models.ai_session_step import AISessionStep
+from app.models.session_handoff import SessionHandoff
 from app.models.flow_proposal import FlowProposal
 from app.models.psa_activity_log import PsaActivityLog
 from app.models.psa_post_log import PsaPostLog
@@ -36,6 +45,7 @@ from app.schemas.flowpilot_analytics import (
     EnhancedPsaMetrics,
     PsaFunnel,
     PsaDailyTrend,
+    EscalationMetrics,
 )
 from app.services.knowledge_gap_service import get_knowledge_gaps, KnowledgeGapReport
 
@@ -727,3 +737,104 @@ async def get_enhanced_psa_metrics(
         push_funnel=push_funnel,
         daily_trend=daily_trend,
     )
+
+
+# ─── Escalation Mode metrics (wedge stat for /escalations queue + analytics page)
+#
+# Pulls all (handoff.claimed_at, first_step_after_claim.created_at) pairs in the
+# window and aggregates avg/median/p95 of the delta in Python. Pilot scale
+# (~1k rows max per account per month) makes this cheaper and clearer than
+# Postgres percentile_cont gymnastics.
+#
+# IMPORTANT: this is the in-product metric only. The "minutes recovered"
+# sales claim requires manual baseline measurement (see The Assignment in
+# docs/plans/2026-04-27-escalation-mode-wedge-design.md).
+
+
+@router.get("/escalations", response_model=EscalationMetrics)
+@limiter.limit("30/minute")
+async def get_escalation_metrics(
+    request: Request,
+    current_user: Annotated[User, Depends(get_current_active_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    _: None = Depends(require_engineer_or_admin),
+    period: str = Query("30d", pattern="^(7d|30d|90d)$"),
+) -> EscalationMetrics:
+    """Time-to-first-action after escalation claim, account-scoped.
+
+    Returns:
+      n_handoffs_claimed: handoffs in window that were claimed by a senior.
+      n_handoffs_with_action: subset where the senior took at least one
+        action (an ai_session_step row created after claimed_at).
+      avg/median/p95_seconds_to_first_action: aggregates of
+        (first_step.created_at - claimed_at) in seconds.
+
+    Excludes handoffs where claimed_at IS NULL (never claimed) and handoffs
+    where no ai_session_step was created after the claim. Both are
+    counted — n_handoffs_claimed includes "no action yet" handoffs so the
+    conversion rate is visible.
+    """
+    if not current_user.account_id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN, detail="No account"
+        )
+
+    account_id = current_user.account_id
+    period_start = _get_period_start(period)
+
+    # First-action timestamp per handoff via correlated scalar subquery.
+    first_action_subq = (
+        select(func.min(AISessionStep.created_at))
+        .where(
+            AISessionStep.session_id == SessionHandoff.session_id,
+            AISessionStep.created_at > SessionHandoff.claimed_at,
+        )
+        .correlate(SessionHandoff)
+        .scalar_subquery()
+    )
+
+    rows = (
+        await db.execute(
+            select(
+                SessionHandoff.claimed_at,
+                first_action_subq.label("first_action_at"),
+            ).where(
+                SessionHandoff.account_id == account_id,
+                SessionHandoff.claimed_at.isnot(None),
+                SessionHandoff.claimed_at >= period_start,
+            )
+        )
+    ).all()
+
+    n_handoffs_claimed = len(rows)
+    deltas: list[float] = []
+    for claimed_at, first_action_at in rows:
+        if first_action_at is None:
+            continue
+        delta_s = (first_action_at - claimed_at).total_seconds()
+        # Floor at zero — clock drift between rows could in theory yield a
+        # tiny negative if a step's created_at races claimed_at. Surface as
+        # 0s rather than absurd negative deltas.
+        if delta_s < 0:
+            delta_s = 0.0
+        deltas.append(delta_s)
+
+    n_handoffs_with_action = len(deltas)
+    if n_handoffs_with_action == 0:
+        return EscalationMetrics(
+            period=period,
+            n_handoffs_claimed=n_handoffs_claimed,
+            n_handoffs_with_action=0,
+        )
+
+    sorted_deltas = sorted(deltas)
+    p95_idx = max(0, int(round(0.95 * (n_handoffs_with_action - 1))))
+
+    return EscalationMetrics(
+        period=period,
+        n_handoffs_claimed=n_handoffs_claimed,
+        n_handoffs_with_action=n_handoffs_with_action,
+        avg_seconds_to_first_action=round(statistics.fmean(deltas), 2),
+        median_seconds_to_first_action=round(statistics.median(deltas), 2),
+        p95_seconds_to_first_action=round(sorted_deltas[p95_idx], 2),
+    )

backend/app/api/endpoints/oauth.py

@@ -0,0 +1,123 @@
+import secrets
+import string
+from datetime import datetime, timezone
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.admin_database import get_admin_db
+from app.core.config import settings
+from app.core.security import create_access_token, create_refresh_token
+from app.models.account import Account
+from app.models.oauth_identity import OAuthIdentity
+from app.models.user import User
+from app.schemas.oauth import OAuthCallbackPayload, OAuthCallbackResponse
+from app.services.billing import BillingService
+from app.services.oauth_providers import (
+    google_exchange_code,
+    microsoft_exchange_code,
+    OAuthProfile,
+)
+
+router = APIRouter(prefix="/auth", tags=["auth-oauth"])
+
+
+def _generate_display_code(length: int = 8) -> str:
+    """Match the helper used by /auth/register — A-Z + 0-9, length 8."""
+    alphabet = string.ascii_uppercase + string.digits
+    return "".join(secrets.choice(alphabet) for _ in range(length))
+
+
+async def _sign_in_or_register(
+    db: AsyncSession, provider: str, profile: OAuthProfile
+) -> tuple[User, bool]:
+    """Returns (user, is_new_user). Idempotent on (provider, provider_subject)."""
+    identity = (
+        await db.execute(
+            select(OAuthIdentity).where(
+                OAuthIdentity.provider == provider,
+                OAuthIdentity.provider_subject == profile.provider_subject,
+            )
+        )
+    ).scalar_one_or_none()
+
+    if identity:
+        user = (
+            await db.execute(select(User).where(User.id == identity.user_id))
+        ).scalar_one()
+        return user, False
+
+    user = (
+        await db.execute(select(User).where(User.email == profile.email))
+    ).scalar_one_or_none()
+    is_new_user = user is None
+    if is_new_user:
+        account = Account(
+            name=f"{profile.name}'s Account",
+            display_code=_generate_display_code(),
+        )
+        db.add(account)
+        await db.flush()
+        user = User(
+            email=profile.email,
+            name=profile.name,
+            password_hash=None,
+            account_id=account.id,
+            account_role="owner",
+            role="engineer",
+            email_verified_at=datetime.now(timezone.utc),
+        )
+        db.add(user)
+        await db.flush()
+        account.owner_id = user.id
+        await db.flush()
+        # start_trial commits internally; flushed account/user above.
+        await BillingService.start_trial(db, account.id)
+
+    db.add(
+        OAuthIdentity(
+            user_id=user.id,
+            provider=provider,
+            provider_subject=profile.provider_subject,
+            provider_email_at_link=profile.email,
+        )
+    )
+    await db.commit()
+    await db.refresh(user)
+    return user, is_new_user
+
+
+@router.post("/google/callback", response_model=OAuthCallbackResponse)
+async def google_callback(
+    payload: OAuthCallbackPayload,
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
+) -> OAuthCallbackResponse:
+    if not settings.GOOGLE_CLIENT_ID:
+        raise HTTPException(status_code=503, detail="Google sign-in not configured")
+    redirect_uri = f"{settings.OAUTH_REDIRECT_BASE}/auth/google/callback"
+    profile = await google_exchange_code(payload.code, redirect_uri)
+    user, is_new = await _sign_in_or_register(db, "google", profile)
+    return OAuthCallbackResponse(
+        access_token=create_access_token({"sub": str(user.id)}),
+        refresh_token=create_refresh_token({"sub": str(user.id)}),
+        is_new_user=is_new,
+    )
+
+
+@router.post("/microsoft/callback", response_model=OAuthCallbackResponse)
+async def microsoft_callback(
+    payload: OAuthCallbackPayload,
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
+) -> OAuthCallbackResponse:
+    if not settings.MS_CLIENT_ID:
+        raise HTTPException(status_code=503, detail="Microsoft sign-in not configured")
+    redirect_uri = f"{settings.OAUTH_REDIRECT_BASE}/auth/microsoft/callback"
+    profile = await microsoft_exchange_code(payload.code, redirect_uri)
+    user, is_new = await _sign_in_or_register(db, "microsoft", profile)
+    return OAuthCallbackResponse(
+        access_token=create_access_token({"sub": str(user.id)}),
+        refresh_token=create_refresh_token({"sub": str(user.id)}),
+        is_new_user=is_new,
+    )

backend/app/api/endpoints/session_handoffs.py

@@ -1,23 +1,28 @@
 """Handoff endpoints — unified park/escalate.
 
-  POST   /ai-sessions/{id}/handoff              — Create handoff
+  POST   /ai-sessions/{id}/handoff               — Create handoff
   GET    /ai-sessions/{id}/handoffs              — Handoff history
   POST   /ai-sessions/{id}/handoffs/{hid}/claim  — Claim session
-  GET    /ai-sessions/queue                       — Team queue
+  GET    /ai-sessions/queue                      — Team queue
+  GET    /ai-sessions/escalations/stream         — SSE: live escalation arrivals
 """
+import asyncio
+import json
 import logging
-from typing import Annotated
+from typing import Annotated, AsyncGenerator
 from uuid import UUID
 
-from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException, Request, status
+from fastapi.responses import StreamingResponse
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from app.api.deps import get_current_active_user, get_db
+from app.api.deps import get_current_active_user, get_db, require_engineer_or_admin
+from app.core.escalation_bus import bus as escalation_bus
 from app.models.user import User
 from app.models.ai_session import AISession
 from app.models.session_handoff import SessionHandoff
-from app.services.handoff_manager import HandoffManager
+from app.services.handoff_manager import HandoffAlreadyClaimedError, HandoffManager
 from app.schemas.session_handoff import (
     HandoffCreateRequest,
     HandoffResponse,
@@ -36,6 +41,7 @@ router = APIRouter(prefix="/ai-sessions/{session_id}", tags=["session-handoffs"]
 async def create_handoff(
     session_id: UUID,
     body: HandoffCreateRequest,
+    background_tasks: BackgroundTasks,
     current_user: Annotated[User, Depends(get_current_active_user)],
     db: Annotated[AsyncSession, Depends(get_db)],
 ) -> HandoffResponse:
@@ -58,12 +64,35 @@ async def create_handoff(
             engineer_notes=body.engineer_notes,
             user_id=current_user.id,
             priority=body.priority,
+            target_user_id=body.target_user_id,
         )
     except ValueError as e:
         raise HTTPException(status_code=400, detail=str(e))
 
+    # For escalate: generate documentation + push to PSA before commit so
+    # the handoff and the PSA-state changes land atomically.
+    if handoff.intent == "escalate":
+        await manager.finalize_escalation(handoff, session, current_user.id)
+
     await db.commit()
-    return HandoffResponse.model_validate(handoff)
+
+    # Best-effort notification dispatch AFTER commit so we never email about
+    # a rolled-back handoff. Failures are swallowed inside the manager —
+    # handoff creation is authoritative; notifications are advisory.
+    if handoff.intent == "escalate":
+        from app.services.handoff_manager import enrich_escalation_async
+
+        await manager.dispatch_escalation_notifications(handoff)
+        # AI enrichment (Sonnet assessment + enhanced escalation_package)
+        # runs in the background after the response is sent so the
+        # escalating engineer doesn't wait on 15-25s of model latency.
+        background_tasks.add_task(
+            enrich_escalation_async, handoff.id, current_user.id
+        )
+
+    return HandoffResponse.model_validate(handoff).model_copy(
+        update={"handed_off_by_name": current_user.name}
+    )
 
 
 @router.get("/handoffs", response_model=list[HandoffResponse])
@@ -86,21 +115,49 @@ async def list_handoffs(
 async def claim_handoff(
     session_id: UUID,
     handoff_id: UUID,
-    current_user: Annotated[User, Depends(get_current_active_user)],
+    current_user: Annotated[User, Depends(require_engineer_or_admin)],
     db: Annotated[AsyncSession, Depends(get_db)],
 ) -> HandoffResponse:
-    """Claim a handed-off session."""
+    """Claim a handed-off session.
+
+    Role-gated to engineer/admin/owner — viewers cannot claim. The race-condition
+    story (two seniors clicking Pick Up simultaneously) depends on auth gating
+    for audit integrity. Codex review flagged this as wedge-relevant; locked
+    in-scope for Escalation Mode v1.
+    """
     manager = HandoffManager(db)
     try:
         handoff = await manager.claim_session(
             handoff_id=handoff_id,
             claiming_user_id=current_user.id,
         )
+    except HandoffAlreadyClaimedError as e:
+        # Loser of the race — the API surfaces structured detail so the
+        # client can render "Already claimed by {name} {time_ago}" without
+        # a follow-up fetch.
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail={
+                "error": "already_claimed",
+                "claimed_by_id": str(e.claimed_by_id),
+                "claimed_by_name": e.claimed_by_name,
+                "claimed_at": e.claimed_at.isoformat(),
+            },
+        )
+    except PermissionError as e:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=str(e))
     except ValueError as e:
         raise HTTPException(status_code=404, detail=str(e))
 
     await db.commit()
-    return HandoffResponse.model_validate(handoff)
+    handed_off_by_name = (
+        handoff.handed_off_by_user.name
+        if handoff.handed_off_by_user
+        else None
+    )
+    return HandoffResponse.model_validate(handoff).model_copy(
+        update={"handed_off_by_name": handed_off_by_name}
+    )
 
 
 @queue_router.get("/queue")
@@ -114,3 +171,83 @@ async def get_queue(
         team_id=current_user.team_id,
         account_id=current_user.account_id,
     )
+
+
+# ─── Live escalation arrivals (SSE) ──────────────────────────────────────────
+#
+# Streams `handoff_created` events to subscribers in the same account_id as
+# the new handoff. Connected EscalationQueue instances prepend the new card
+# with the locked 200ms slide-in. Account-scoped: cross-tenant leakage is
+# prevented at the bus.publish boundary (only handoff.account_id subscribers
+# are notified) and re-enforced here by binding the subscription to
+# current_user.account_id.
+#
+# Heartbeat: a `: keepalive\n\n` SSE comment every 25s keeps the connection
+# alive through Railway / nginx default 60s idle timeouts. Reconnect policy
+# is on the client (browser EventSource auto-reconnects; our fetch-based
+# reader retries with backoff).
+
+
+_HEARTBEAT_INTERVAL_S = 25
+_QUEUE_GET_TIMEOUT_S = 25  # < heartbeat so heartbeat fires reliably
+
+
+@queue_router.get("/escalations/stream")
+async def stream_escalations(
+    request: Request,
+    current_user: Annotated[
+        User,
+        Depends(require_engineer_or_admin, scope="function"),
+    ],
+):
+    """SSE stream of new escalation arrivals for the current user's account.
+
+    Role-gated to engineer/admin/owner so viewers can't subscribe (matches
+    the queue + claim role surface). One open connection per browser tab is
+    expected; the bus handles fan-out.
+    """
+    if not current_user.account_id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN, detail="No account"
+        )
+
+    account_id = current_user.account_id
+
+    async def event_generator() -> AsyncGenerator[str, None]:
+        queue = await escalation_bus.subscribe(account_id)
+        try:
+            # Initial hello so the client knows the stream is live.
+            yield (
+                "event: ready\n"
+                f"data: {json.dumps({'account_id': str(account_id)})}\n\n"
+            )
+
+            while True:
+                if await request.is_disconnected():
+                    break
+                try:
+                    event = await asyncio.wait_for(
+                        queue.get(), timeout=_QUEUE_GET_TIMEOUT_S
+                    )
+                except asyncio.TimeoutError:
+                    # Heartbeat keeps the connection alive through proxies.
+                    yield ": keepalive\n\n"
+                    continue
+
+                event_type = event.get("type", "message")
+                yield (
+                    f"event: {event_type}\n"
+                    f"data: {json.dumps(event)}\n\n"
+                )
+        finally:
+            await escalation_bus.unsubscribe(account_id, queue)
+
+    return StreamingResponse(
+        event_generator(),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "Connection": "keep-alive",
+            "X-Accel-Buffering": "no",
+        },
+    )

backend/app/api/endpoints/session_suggested_fixes.py

@@ -318,6 +318,11 @@ async def patch_suggested_fix_outcome(
             status_code=status.HTTP_400_BAD_REQUEST,
             detail="notes are required when outcome is applied_partial",
         )
+    if body.outcome == "applied_pending" and not (body.notes and body.notes.strip()):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="notes are required when outcome is applied_pending",
+        )
 
     TERMINAL = {"applied_success", "applied_failed", "dismissed"}
     if fix.status in TERMINAL:
@@ -329,6 +334,10 @@ async def patch_suggested_fix_outcome(
     fix.status = body.outcome
     if body.outcome == "applied_partial":
         fix.partial_notes = (body.notes or "").strip() or None
+    elif body.outcome == "applied_pending":
+        # Pending is parked, not terminal — keep applied_at, do NOT stamp
+        # verified_at. Reason explains what the engineer is waiting on.
+        fix.pending_reason = (body.notes or "").strip() or None
     elif body.outcome == "applied_failed":
         fix.failure_reason = (body.notes or "").strip() or None
         fix.verified_at = now

backend/app/api/endpoints/sidebar.py

@@ -161,7 +161,7 @@ async def get_sidebar_stats(
             select(func.count()).where(
                 and_(
                     esc_scope,
-                    AISession.status == "requesting_escalation",
+                    AISession.status.in_(("requesting_escalation", "escalated")),
                 )
             )
         )

backend/app/api/endpoints/webhooks.py

@@ -1,10 +1,10 @@
 import logging
-from fastapi import APIRouter, Request, HTTPException, status, Depends
+from fastapi import APIRouter, Request, HTTPException, Depends
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from app.core.database import get_db
+from app.core.admin_database import get_admin_db
 from app.core.config import settings
-from app.core.stripe_handlers import WEBHOOK_HANDLERS
+from app.services.billing import BillingService
 
 logger = logging.getLogger(__name__)
 
@@ -14,49 +14,36 @@ router = APIRouter(prefix="/webhooks", tags=["webhooks"])
 @router.post("/stripe")
 async def stripe_webhook(
     request: Request,
-    db: AsyncSession = Depends(get_db),
+    db: AsyncSession = Depends(get_admin_db),
 ):
-    """Handle Stripe webhook events.
+    """Stripe webhook handler. Public endpoint; signature verification is the
+    only gate. Idempotency via stripe_events table.
 
-    Returns 200 for all events to prevent Stripe retries.
-    Actual processing happens only when Stripe is configured.
+    Returns 200 even when Stripe is not configured — keeps the receiver
+    permissive for local dev.
     """
-    if not settings.stripe_enabled:
+    if not settings.stripe_enabled or not settings.STRIPE_WEBHOOK_SECRET:
         return {"status": "ok", "message": "Stripe not configured, event ignored"}
 
     payload = await request.body()
     sig_header = request.headers.get("stripe-signature")
-
     if not sig_header:
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail="Missing stripe-signature header"
-        )
+        raise HTTPException(status_code=400, detail="Missing stripe-signature header")
 
-    # Verify webhook signature
     try:
         import stripe
         stripe.api_key = settings.STRIPE_SECRET_KEY
         event = stripe.Webhook.construct_event(
             payload, sig_header, settings.STRIPE_WEBHOOK_SECRET
         )
-    except ImportError:
-        logger.warning("stripe package not installed, cannot verify webhook")
-        return {"status": "ok", "message": "stripe package not installed"}
     except Exception as e:
-        logger.error("Stripe webhook signature verification failed: %s", e)
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail="Invalid signature"
-        )
+        logger.warning("stripe webhook bad signature: %s", e)
+        raise HTTPException(status_code=400, detail="Invalid signature")
 
-    event_type = event.get("type", "")
-    handler = WEBHOOK_HANDLERS.get(event_type)
-
-    if handler:
-        try:
-            await handler(event, db)
-        except Exception:
-            logger.exception("Error handling Stripe event %s", event_type)
-
-    return {"status": "ok"}
+    applied = await BillingService.apply_subscription_event(
+        db,
+        event_id=event["id"],
+        event_type=event["type"],
+        payload={"data": event["data"]},
+    )
+    return {"status": "ok", "applied": applied}

backend/app/api/router.py

@@ -1,6 +1,10 @@
 from fastapi import APIRouter, Depends
 
-from app.api.deps import require_tenant_context
+from app.api.deps import (
+    require_tenant_context,
+    require_active_subscription,
+    require_verified_email_after_grace,
+)
 from app.api.endpoints import (
     admin,
     admin_audit,
@@ -19,6 +23,7 @@ from app.api.endpoints import (
     analytics,
     assistant_chat,
     auth,
+    billing,
     beta_feedback,
     beta_signup,
     branding,
@@ -36,6 +41,7 @@ from app.api.endpoints import (
     maintenance_schedules,
     network_diagrams,
     notifications,
+    oauth as oauth_endpoints,
     onboarding,
     public_templates,
     ratings,
@@ -77,6 +83,8 @@ api_router = APIRouter()
 # in Phase 1. This will need revisiting in Phase 2 when `users` gets RLS.
 # ---------------------------------------------------------------------------
 api_router.include_router(auth.router)
+api_router.include_router(oauth_endpoints.router)
+api_router.include_router(billing.router)     # Reachable when subscription locked
 api_router.include_router(shared.router)       # Public share links (no auth)
 api_router.include_router(shares.public_router)  # Public session share links (optional auth)
 api_router.include_router(beta_signup.router)
@@ -102,23 +110,36 @@ api_router.include_router(admin_survey.router)
 api_router.include_router(admin_gallery.router)
 # ---------------------------------------------------------------------------
 # User-facing endpoints — tenant context required
+#
+# _tenant_deps:  routers that only require an authenticated user inside a
+#                tenant (auth/account/admin/non-Pro feature surfaces).
+# _pro_deps:     routers gated behind an active Pro subscription. Adds
+#                require_active_subscription which raises 402 unless the
+#                account's Subscription is active/complimentary/past_due or
+#                trialing-with-time-remaining. Allowlisted paths in deps.py
+#                bypass the gate for billing/account admin/auth flows.
 # ---------------------------------------------------------------------------
 _tenant_deps = [Depends(require_tenant_context)]
+_pro_deps = [
+    Depends(require_tenant_context),
+    Depends(require_active_subscription),
+    Depends(require_verified_email_after_grace),
+]
 
-api_router.include_router(trees.router, dependencies=_tenant_deps)
+api_router.include_router(trees.router, dependencies=_pro_deps)
 api_router.include_router(sidebar.router, dependencies=_tenant_deps)
-api_router.include_router(sessions.router, dependencies=_tenant_deps)
+api_router.include_router(sessions.router, dependencies=_pro_deps)
 api_router.include_router(invite.router, dependencies=_tenant_deps)
 api_router.include_router(categories.router, dependencies=_tenant_deps)
 api_router.include_router(tags.router, dependencies=_tenant_deps)
 api_router.include_router(folders.router, dependencies=_tenant_deps)
-api_router.include_router(step_categories.router, dependencies=_tenant_deps)
-api_router.include_router(steps.router, dependencies=_tenant_deps)
+api_router.include_router(step_categories.router, dependencies=_pro_deps)
+api_router.include_router(steps.router, dependencies=_pro_deps)
 api_router.include_router(accounts.router, dependencies=_tenant_deps)
 api_router.include_router(shares.router, dependencies=_tenant_deps)
 api_router.include_router(tree_markdown.router, dependencies=_tenant_deps)
 api_router.include_router(ratings.router, dependencies=_tenant_deps)
-api_router.include_router(analytics.router, dependencies=_tenant_deps)
+api_router.include_router(analytics.router, dependencies=_pro_deps)
 api_router.include_router(target_lists.router, dependencies=_tenant_deps)
 api_router.include_router(maintenance_schedules.router, dependencies=_tenant_deps)
 api_router.include_router(feedback.router, dependencies=_tenant_deps)
@@ -126,31 +147,31 @@ api_router.include_router(ai_builder.router, dependencies=_tenant_deps)
 api_router.include_router(ai_fix.router, dependencies=_tenant_deps)
 api_router.include_router(ai_chat.router, dependencies=_tenant_deps)
 api_router.include_router(copilot.router, dependencies=_tenant_deps)
-api_router.include_router(assistant_chat.router, dependencies=_tenant_deps)
+api_router.include_router(assistant_chat.router, dependencies=_pro_deps)
 api_router.include_router(tree_transfer.router, dependencies=_tenant_deps)
 api_router.include_router(ai_suggestions.router, dependencies=_tenant_deps)
 api_router.include_router(kb_accelerator.router, dependencies=_tenant_deps)
-api_router.include_router(scripts.router, dependencies=_tenant_deps)
-api_router.include_router(integrations.router, dependencies=_tenant_deps)
+api_router.include_router(scripts.router, dependencies=_pro_deps)
+api_router.include_router(integrations.router, dependencies=_pro_deps)
 api_router.include_router(onboarding.router, dependencies=_tenant_deps)
 api_router.include_router(branding.router, dependencies=_tenant_deps)
 api_router.include_router(supporting_data.router, dependencies=_tenant_deps)
 api_router.include_router(network_diagrams.router, dependencies=_tenant_deps)
 # session_handoffs queue router must come before ai_sessions to avoid conflict
-api_router.include_router(session_handoffs.queue_router, dependencies=_tenant_deps)
-api_router.include_router(session_resolutions.router, dependencies=_tenant_deps)
+api_router.include_router(session_handoffs.queue_router, dependencies=_pro_deps)
+api_router.include_router(session_resolutions.router, dependencies=_pro_deps)
 # session_facts mounts under /ai-sessions/{id}/facts — register before ai_sessions
 # so the {session_id}/facts subpaths take precedence over any future generic catchalls.
-api_router.include_router(session_facts.router, dependencies=_tenant_deps)
-api_router.include_router(session_suggested_fixes.router, dependencies=_tenant_deps)
+api_router.include_router(session_facts.router, dependencies=_pro_deps)
+api_router.include_router(session_suggested_fixes.router, dependencies=_pro_deps)
 api_router.include_router(draft_templates.router, dependencies=_tenant_deps)
-api_router.include_router(ai_sessions.router, dependencies=_tenant_deps)
-api_router.include_router(flow_proposals.router, dependencies=_tenant_deps)
-api_router.include_router(flowpilot_analytics.router, dependencies=_tenant_deps)
+api_router.include_router(ai_sessions.router, dependencies=_pro_deps)
+api_router.include_router(flow_proposals.router, dependencies=_pro_deps)
+api_router.include_router(flowpilot_analytics.router, dependencies=_pro_deps)
 api_router.include_router(notifications.router, dependencies=_tenant_deps)
 api_router.include_router(uploads.router, dependencies=_tenant_deps)
-api_router.include_router(script_builder.router, dependencies=_tenant_deps)
+api_router.include_router(script_builder.router, dependencies=_pro_deps)
 api_router.include_router(beta_feedback.router, dependencies=_tenant_deps)
-api_router.include_router(session_branches.router, dependencies=_tenant_deps)
-api_router.include_router(session_handoffs.router, dependencies=_tenant_deps)
+api_router.include_router(session_branches.router, dependencies=_pro_deps)
+api_router.include_router(session_handoffs.router, dependencies=_pro_deps)
 api_router.include_router(device_types.router, dependencies=_tenant_deps)

backend/app/core/config.py

@@ -94,11 +94,12 @@ class Settings(BaseSettings):
     STRIPE_SECRET_KEY: Optional[str] = None
     STRIPE_PUBLISHABLE_KEY: Optional[str] = None
     STRIPE_WEBHOOK_SECRET: Optional[str] = None
+    SELF_SERVE_ENABLED: bool = False
 
     @property
     def stripe_enabled(self) -> bool:
         """Check if Stripe is configured."""
-        return self.STRIPE_SECRET_KEY is not None and self.STRIPE_WEBHOOK_SECRET is not None
+        return bool(self.STRIPE_SECRET_KEY)
 
     # AI Flow Builder
     ANTHROPIC_API_KEY: Optional[str] = None
@@ -111,6 +112,16 @@ class Settings(BaseSettings):
     GOOGLE_AI_API_KEY: Optional[str] = None
     AI_MODEL_GEMINI: str = "gemini-2.5-flash"
     AI_MODEL_ANTHROPIC: str = "claude-sonnet-4-6"
+    # Bound for the diagnostic assessment Sonnet call. Generation runs in a
+    # FastAPI BackgroundTask (commit e8ba74e), so this no longer blocks the
+    # senior's click — only how long we wait before publishing
+    # `handoff_assessment_ready` with has_assessment=false. 15s was hitting
+    # tail latency on Sonnet (timeout 03:57:35 in field testing 2026-04-29),
+    # leaving the magic-moment placeholder permanent. 45s is the right
+    # ceiling: well above Sonnet p99 for a 500-token output, far enough
+    # below "the senior gives up watching" that we still surface SOMETHING
+    # on persistent slowness.
+    ESCALATION_AI_ASSESSMENT_TIMEOUT_SECONDS: int = 45
 
     # Model tier routing — maps action types to model tiers
     AI_MODEL_TIERS: dict[str, str] = {
@@ -183,6 +194,13 @@ class Settings(BaseSettings):
         """Check if ConnectWise integration is configured."""
         return self.CW_CLIENT_ID is not None
 
+    # OAuth providers (self-serve signup)
+    GOOGLE_CLIENT_ID: Optional[str] = None
+    GOOGLE_CLIENT_SECRET: Optional[str] = None
+    MS_CLIENT_ID: Optional[str] = None
+    MS_CLIENT_SECRET: Optional[str] = None
+    OAUTH_REDIRECT_BASE: str = "http://localhost:5173"
+
     # Monitoring
     SENTRY_DSN: Optional[str] = None
 

backend/app/core/escalation_bus.py

@@ -0,0 +1,105 @@
+"""In-memory pub/sub bus for live escalation events.
+
+Single-process, non-durable. When a handoff fires, every connected SSE
+subscriber for the same `account_id` receives the event. Subscribers come
+and go as senior techs open and close the EscalationQueue page.
+
+Pre-PMF scale (3 pilots × 5-20 techs/MSP = ~15-60 concurrent subscribers
+total, single Railway replica) makes in-memory the right call. When the
+deployment scales horizontally, swap this for Redis pub/sub or similar —
+the public surface (`publish` / `subscribe`) is intentionally narrow so
+the swap is local.
+
+Events are JSON-serializable dicts. `publish()` is non-blocking (drops the
+event if a subscriber's queue is full rather than back-pressuring the
+caller). `subscribe()` MUST be paired with `unsubscribe()` in a finally
+block, or you leak queues.
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any
+from uuid import UUID
+
+logger = logging.getLogger(__name__)
+
+
+# Bound how many unconsumed events can sit in a subscriber's queue before
+# we start dropping. 64 is generous for the queue-page use case; if a
+# subscriber is that far behind, they're probably gone or stuck.
+_QUEUE_MAXSIZE = 64
+
+
+class EscalationBus:
+    """Account-scoped pub/sub for escalation arrival events."""
+
+    def __init__(self) -> None:
+        self._subscribers: dict[UUID, set[asyncio.Queue[dict[str, Any]]]] = {}
+        self._lock = asyncio.Lock()
+
+    @staticmethod
+    def _normalize_account_id(account_id: UUID | str) -> UUID:
+        return account_id if isinstance(account_id, UUID) else UUID(str(account_id))
+
+    async def subscribe(self, account_id: UUID | str) -> asyncio.Queue[dict[str, Any]]:
+        """Register a new subscriber queue for an account.
+
+        Caller must invoke `unsubscribe(account_id, queue)` when the
+        consumer disconnects.
+        """
+        normalized_account_id = self._normalize_account_id(account_id)
+        queue: asyncio.Queue[dict[str, Any]] = asyncio.Queue(
+            maxsize=_QUEUE_MAXSIZE
+        )
+        async with self._lock:
+            self._subscribers.setdefault(normalized_account_id, set()).add(queue)
+        return queue
+
+    async def unsubscribe(
+        self, account_id: UUID | str, queue: asyncio.Queue[dict[str, Any]]
+    ) -> None:
+        normalized_account_id = self._normalize_account_id(account_id)
+        async with self._lock:
+            subs = self._subscribers.get(normalized_account_id)
+            if subs is None:
+                return
+            subs.discard(queue)
+            if not subs:
+                self._subscribers.pop(normalized_account_id, None)
+
+    async def publish(self, account_id: UUID | str, event: dict[str, Any]) -> int:
+        """Fan event out to every subscriber for `account_id`.
+
+        Returns the number of subscribers that successfully received the
+        event. Drops the event for any subscriber whose queue is full
+        (logs at warning level).
+        """
+        normalized_account_id = self._normalize_account_id(account_id)
+        async with self._lock:
+            subs = list(self._subscribers.get(normalized_account_id, ()))
+        if not subs:
+            return 0
+        delivered = 0
+        for queue in subs:
+            try:
+                queue.put_nowait(event)
+                delivered += 1
+            except asyncio.QueueFull:
+                logger.warning(
+                    "EscalationBus: dropped event for full subscriber queue "
+                    "(account_id=%s, event=%s)",
+                    normalized_account_id,
+                    event.get("type", "?"),
+                )
+        return delivered
+
+    def subscriber_count(self, account_id: UUID | str) -> int:
+        """Diagnostic — number of active subscribers for an account."""
+        normalized_account_id = self._normalize_account_id(account_id)
+        return len(self._subscribers.get(normalized_account_id, ()))
+
+
+# Module-level singleton. FastAPI imports this; `subscribe()` and `publish()`
+# are coroutine-safe via the internal Lock.
+bus = EscalationBus()

backend/app/models/__init__.py

@@ -62,6 +62,10 @@ from .session_fact import SessionFact
 from .session_suggested_fix import SessionSuggestedFix
 from .draft_template import DraftTemplate
 from .account_settings import AccountSettings
+from .oauth_identity import OAuthIdentity  # noqa: F401
+from .plan_billing import PlanBilling  # noqa: F401
+from .sales_lead import SalesLead  # noqa: F401
+from .stripe_event import StripeEvent  # noqa: F401
 
 __all__ = [
     "User",
@@ -138,4 +142,8 @@ __all__ = [
     "SessionSuggestedFix",
     "DraftTemplate",
     "AccountSettings",
+    "OAuthIdentity",
+    "PlanBilling",
+    "SalesLead",
+    "StripeEvent",
 ]

backend/app/models/account.py

@@ -48,6 +48,8 @@ class Account(Base):
     branding_logo_url: Mapped[Optional[str]] = mapped_column(String(500), nullable=True)
     branding_primary_color: Mapped[Optional[str]] = mapped_column(String(7), nullable=True)  # hex like #06b6d4
     branding_company_name: Mapped[Optional[str]] = mapped_column(String(200), nullable=True)
+    team_size_bucket: Mapped[Optional[str]] = mapped_column(String(20), nullable=True)
+    primary_psa: Mapped[Optional[str]] = mapped_column(String(20), nullable=True)
 
     # SSO / SAML groundwork (Task 11)
     sso_enabled: Mapped[bool] = mapped_column(Boolean, default=False, server_default="false")

backend/app/models/account_invite.py

@@ -27,6 +27,8 @@ class AccountInvite(Base):
     expires_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True), nullable=True)
     created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now(timezone.utc))
     used_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True), nullable=True)
+    revoked_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True), nullable=True)
+    email_sent_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True), nullable=True)
 
     # Relationships
     account: Mapped["Account"] = relationship("Account")
@@ -37,6 +39,10 @@ class AccountInvite(Base):
     def is_used(self) -> bool:
         return self.accepted_by_id is not None
 
+    @property
+    def is_revoked(self) -> bool:
+        return self.revoked_at is not None
+
     @property
     def is_expired(self) -> bool:
         if self.expires_at is None:
@@ -45,4 +51,4 @@ class AccountInvite(Base):
 
     @property
     def is_valid(self) -> bool:
-        return not self.is_used and not self.is_expired
+        return not self.is_used and not self.is_expired and not self.is_revoked

backend/app/models/oauth_identity.py

@@ -0,0 +1,36 @@
+import uuid
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING
+from sqlalchemy import String, DateTime, ForeignKey, UniqueConstraint, Index
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+from sqlalchemy.dialects.postgresql import UUID
+from app.core.database import Base
+
+if TYPE_CHECKING:
+    from app.models.user import User
+
+
+class OAuthIdentity(Base):
+    __tablename__ = "oauth_identities"
+    __table_args__ = (
+        UniqueConstraint("provider", "provider_subject", name="uq_oauth_identities_provider_subject"),
+        Index("ix_oauth_identities_user_id", "user_id"),
+    )
+
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    user_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True), ForeignKey("users.id", ondelete="CASCADE"), nullable=False
+    )
+    provider: Mapped[str] = mapped_column(String(20), nullable=False)
+    provider_subject: Mapped[str] = mapped_column(String(255), nullable=False)
+    provider_email_at_link: Mapped[str] = mapped_column(String(255), nullable=False)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=lambda: datetime.now(timezone.utc),
+        onupdate=lambda: datetime.now(timezone.utc),
+    )
+
+    user: Mapped["User"] = relationship("User", backref="oauth_identities")

backend/app/models/plan_billing.py

@@ -0,0 +1,31 @@
+from datetime import datetime, timezone
+from typing import Optional
+from sqlalchemy import String, Integer, Boolean, DateTime, ForeignKey, Text
+from sqlalchemy.orm import Mapped, mapped_column
+from app.core.database import Base
+
+
+class PlanBilling(Base):
+    __tablename__ = "plan_billing"
+
+    plan: Mapped[str] = mapped_column(
+        String(50), ForeignKey("plan_limits.plan"), primary_key=True
+    )
+    display_name: Mapped[str] = mapped_column(String(255), nullable=False)
+    description: Mapped[Optional[str]] = mapped_column(Text, nullable=True)
+    monthly_price_cents: Mapped[Optional[int]] = mapped_column(Integer, nullable=True)
+    annual_price_cents: Mapped[Optional[int]] = mapped_column(Integer, nullable=True)
+    stripe_product_id: Mapped[Optional[str]] = mapped_column(String(255), nullable=True)
+    stripe_monthly_price_id: Mapped[Optional[str]] = mapped_column(String(255), nullable=True)
+    stripe_annual_price_id: Mapped[Optional[str]] = mapped_column(String(255), nullable=True)
+    is_public: Mapped[bool] = mapped_column(Boolean, nullable=False, default=True)
+    is_archived: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)
+    sort_order: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=lambda: datetime.now(timezone.utc),
+        onupdate=lambda: datetime.now(timezone.utc),
+    )

backend/app/models/sales_lead.py

@@ -0,0 +1,28 @@
+import uuid
+from datetime import datetime, timezone
+from typing import Optional
+from sqlalchemy import String, DateTime, Text, Index
+from sqlalchemy.orm import Mapped, mapped_column
+from sqlalchemy.dialects.postgresql import UUID
+from app.core.database import Base
+
+
+class SalesLead(Base):
+    __tablename__ = "sales_leads"
+    __table_args__ = (Index("ix_sales_leads_email", "email"),)
+
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    email: Mapped[str] = mapped_column(String(255), nullable=False)
+    name: Mapped[str] = mapped_column(String(255), nullable=False)
+    company: Mapped[str] = mapped_column(String(255), nullable=False)
+    team_size: Mapped[Optional[str]] = mapped_column(String(20), nullable=True)
+    message: Mapped[Optional[str]] = mapped_column(Text, nullable=True)
+    source: Mapped[str] = mapped_column(String(50), nullable=False)
+    posthog_distinct_id: Mapped[Optional[str]] = mapped_column(String(255), nullable=True)
+    status: Mapped[str] = mapped_column(String(20), nullable=False, default="new")
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now(timezone.utc))
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=lambda: datetime.now(timezone.utc),
+        onupdate=lambda: datetime.now(timezone.utc),
+    )

backend/app/models/session_suggested_fix.py

@@ -37,7 +37,7 @@ class SessionSuggestedFix(Base):
         ),
         CheckConstraint(
             "status IN ('proposed', 'applied_success', 'applied_failed', "
-            "'applied_partial', 'dismissed')",
+            "'applied_partial', 'applied_pending', 'dismissed')",
             name="ck_session_suggested_fixes_status",
         ),
     )
@@ -81,6 +81,7 @@ class SessionSuggestedFix(Base):
         DateTime(timezone=True), nullable=True
     )
     partial_notes: Mapped[str | None] = mapped_column(Text, nullable=True)
+    pending_reason: Mapped[str | None] = mapped_column(Text, nullable=True)
     failure_reason: Mapped[str | None] = mapped_column(Text, nullable=True)
     ai_outcome_proposal: Mapped[dict[str, Any] | None] = mapped_column(
         JSONB, nullable=True

backend/app/models/stripe_event.py

@@ -0,0 +1,17 @@
+from datetime import datetime, timezone
+from sqlalchemy import String, DateTime, Index
+from sqlalchemy.orm import Mapped, mapped_column
+from sqlalchemy.dialects.postgresql import JSONB
+from app.core.database import Base
+
+
+class StripeEvent(Base):
+    __tablename__ = "stripe_events"
+    __table_args__ = (Index("ix_stripe_events_event_type", "event_type"),)
+
+    id: Mapped[str] = mapped_column(String(255), primary_key=True)  # Stripe event id
+    event_type: Mapped[str] = mapped_column(String(100), nullable=False)
+    processed_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
+    )
+    payload_excerpt: Mapped[dict] = mapped_column(JSONB, nullable=False, default=dict)

backend/app/models/subscription.py

@@ -32,8 +32,20 @@ class Subscription(Base):
 
     @property
     def is_active(self) -> bool:
-        return self.status in ("active", "trialing")
+        return self.status in ("active", "trialing", "complimentary")
 
     @property
     def is_paid(self) -> bool:
-        return self.plan in ("pro", "team")
+        # Excludes complimentary and trialing so MRR/paid-customer metrics aren't inflated.
+        return self.plan in ("pro", "team") and self.status not in ("complimentary", "trialing")
+
+    @property
+    def has_pro_entitlement(self) -> bool:
+        """True if the account can access Pro features right now."""
+        if self.plan in ("pro", "team"):
+            if self.status in ("active", "complimentary"):
+                return True
+        if self.status == "trialing" and self.current_period_end is not None:
+            from datetime import datetime, timezone
+            return self.current_period_end > datetime.now(timezone.utc)
+        return False

backend/app/models/user.py

@@ -1,7 +1,7 @@
 import uuid
 from datetime import datetime, timezone
 from typing import Optional, TYPE_CHECKING
-from sqlalchemy import String, DateTime, ForeignKey, Boolean, CheckConstraint, Text
+from sqlalchemy import String, DateTime, ForeignKey, Boolean, CheckConstraint, Text, Integer
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 from sqlalchemy.dialects.postgresql import UUID
 from app.core.database import Base
@@ -33,7 +33,7 @@ class User(Base):
         default=uuid.uuid4
     )
     email: Mapped[str] = mapped_column(String(255), unique=True, nullable=False, index=True)
-    password_hash: Mapped[str] = mapped_column(String(255), nullable=False)
+    password_hash: Mapped[Optional[str]] = mapped_column(String(255), nullable=True)
     name: Mapped[str] = mapped_column(String(255), nullable=False)
     role: Mapped[str] = mapped_column(String(50), nullable=False, default="engineer")
     is_super_admin: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)
@@ -76,6 +76,8 @@ class User(Base):
 
     # Onboarding
     onboarding_dismissed: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False, server_default="false")
+    role_at_signup: Mapped[Optional[str]] = mapped_column(String(50), nullable=True)
+    onboarding_step_completed: Mapped[Optional[int]] = mapped_column(Integer, nullable=True)
 
     # Branding (solo pros without a team)
     logo_data: Mapped[Optional[str]] = mapped_column(Text, nullable=True)

backend/app/schemas/account.py

@@ -42,3 +42,12 @@ class AccountInviteResponse(BaseModel):
     used_at: Optional[datetime] = None
 
     model_config = {"from_attributes": True}
+
+
+class AccountInviteBulkCreate(BaseModel):
+    invites: list[AccountInviteCreate]
+
+
+class AccountInviteBulkResponse(BaseModel):
+    created: list[AccountInviteResponse]
+    failed: list[dict]  # entries shaped {"email": str, "error": str}

backend/app/schemas/billing.py

@@ -0,0 +1,40 @@
+from typing import Literal, Optional, Dict, Any
+from datetime import datetime
+from pydantic import BaseModel
+
+
+class CheckoutSessionCreate(BaseModel):
+    plan: Literal["pro", "starter", "team", "enterprise"]
+    seats: int
+    billing_interval: Literal["monthly", "annual"] = "monthly"
+
+
+class CheckoutSessionResponse(BaseModel):
+    url: str
+
+
+class SubscriptionState(BaseModel):
+    status: str
+    plan: str
+    current_period_start: Optional[datetime]
+    current_period_end: Optional[datetime]
+    cancel_at_period_end: bool
+    seat_limit: Optional[int]
+    has_pro_entitlement: bool
+    is_paid: bool
+
+
+class PlanBillingState(BaseModel):
+    display_name: str
+    description: Optional[str] = None
+    monthly_price_cents: Optional[int] = None
+    annual_price_cents: Optional[int] = None
+
+    model_config = {"from_attributes": True}
+
+
+class BillingStateResponse(BaseModel):
+    subscription: SubscriptionState
+    plan_billing: Optional[PlanBillingState]
+    plan_limits: Dict[str, Any]
+    enabled_features: Dict[str, bool]

backend/app/schemas/flowpilot_analytics.py

@@ -124,3 +124,26 @@ class FlowPilotDashboard(BaseModel):
     confidence_breakdown: ConfidenceBreakdown
     knowledge_coverage: KnowledgeCoverage
     psa_metrics: PsaMetrics | None = None
+
+
+class EscalationMetrics(BaseModel):
+    """In-product time-to-first-action metric for the Escalation Mode wedge.
+
+    NOTE: this is the *in-product* metric (post-claim time-to-first-action). The
+    "minutes recovered" sales claim requires a manual baseline measurement of the
+    pre-Escalation-Mode verbal-handoff time. See
+    docs/plans/2026-04-27-escalation-mode-wedge-design.md for the two-metric
+    framing — do not roll this number alone into "minutes recovered."
+    """
+
+    period: str
+    n_handoffs_claimed: int
+    n_handoffs_with_action: int
+    avg_seconds_to_first_action: float | None = None
+    median_seconds_to_first_action: float | None = None
+    p95_seconds_to_first_action: float | None = None
+    metric_definition: str = (
+        "elapsed_seconds(first ai_session_step in session where "
+        "created_at > SessionHandoff.claimed_at) — measures post-claim activity "
+        "lag, NOT verbal-handoff savings. Pair with manual baseline."
+    )

backend/app/schemas/oauth.py

@@ -0,0 +1,13 @@
+from pydantic import BaseModel
+
+
+class OAuthCallbackPayload(BaseModel):
+    code: str
+    state: str | None = None
+
+
+class OAuthCallbackResponse(BaseModel):
+    access_token: str
+    refresh_token: str
+    token_type: str = "bearer"
+    is_new_user: bool

backend/app/schemas/session_handoff.py

@@ -10,12 +10,18 @@ class HandoffCreateRequest(BaseModel):
     intent: str = Field(..., pattern="^(park|escalate)$")
     engineer_notes: str | None = None
     priority: str = Field("normal", pattern="^(normal|elevated)$")
+    # Optional escalation target — if set, only this user is the named
+    # recipient. Notification dispatch fans out to all engineer/admin/owner
+    # users in the account either way; this just records the original
+    # engineer's preferred recipient on the session for audit/UX.
+    target_user_id: UUID | None = None
 
 
 class HandoffResponse(BaseModel):
     id: UUID
     session_id: UUID
     handed_off_by: UUID
+    handed_off_by_name: str | None = None
     intent: str
     source_branch_id: UUID | None
     snapshot: dict[str, Any]

backend/app/schemas/session_suggested_fix.py

@@ -20,6 +20,7 @@ FixStatus = Literal[
     "applied_success",
     "applied_failed",
     "applied_partial",
+    "applied_pending",
     "dismissed",
 ]
 
@@ -40,6 +41,7 @@ class SessionSuggestedFixResponse(BaseModel):
     applied_at: datetime | None
     verified_at: datetime | None
     partial_notes: str | None
+    pending_reason: str | None
     failure_reason: str | None
     ai_outcome_proposal: dict[str, Any] | None
 
@@ -91,7 +93,11 @@ class SessionSuggestedFixDecisionResponse(BaseModel):
 # Subset of FixStatus that the engineer can set via the outcome endpoint —
 # `proposed` is excluded because you can't un-decide a fix back to "proposed".
 FixOutcome = Literal[
-    "applied_success", "applied_failed", "applied_partial", "dismissed"
+    "applied_success",
+    "applied_failed",
+    "applied_partial",
+    "applied_pending",
+    "dismissed",
 ]
 
 
@@ -103,14 +109,18 @@ class SessionSuggestedFixOutcomeRequest(BaseModel):
     engineer took); outcome captures whether the fix actually worked.
 
     Allowed transitions:
-    - from `proposed` or `applied_partial`: any outcome is valid
-      (partial is parked, not terminal — the engineer may update notes,
-      abandon via dismiss, or advance to success/failed)
+    - from `proposed`, `applied_partial`, or `applied_pending`: any outcome
+      is valid. Partial means "did some of it"; pending means "did all of
+      it but verification is deferred (waiting on client, async sync, etc)".
+      Both are parked, not terminal — the engineer may advance them to
+      success/failed/dismiss.
     - from any terminal outcome (`applied_success`, `applied_failed`,
       `dismissed`): server returns 409
     """
     outcome: FixOutcome
-    # Required for applied_partial, optional for applied_failed, ignored otherwise.
+    # Required for applied_partial AND applied_pending; optional for
+    # applied_failed; ignored otherwise. For pending, this is the
+    # "what are you waiting on?" reason (e.g. "client power-cycling router").
     notes: str | None = Field(None, max_length=500)
 
 

backend/app/services/billing.py

@@ -0,0 +1,296 @@
+"""Single billing service module. Stripe is the only impl — no provider
+abstraction. Account row is canonical local state; Stripe is canonical
+remote state; the webhook handler bridges the two."""
+from datetime import datetime, timezone, timedelta
+
+import stripe
+from sqlalchemy import select
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.config import settings
+from app.models.account import Account
+from app.models.plan_billing import PlanBilling
+from app.models.stripe_event import StripeEvent
+from app.models.subscription import Subscription
+
+
+TRIAL_DAYS = 14
+
+
+class BillingService:
+    @staticmethod
+    async def start_trial(db: AsyncSession, account_id) -> Subscription:
+        """Idempotent. Creates a trialing Subscription on Pro for the account if
+        one doesn't exist; otherwise returns the existing row."""
+        result = await db.execute(
+            select(Subscription).where(Subscription.account_id == account_id)
+        )
+        existing = result.scalar_one_or_none()
+        if existing is not None:
+            return existing
+
+        sub = Subscription(
+            account_id=account_id,
+            plan="pro",
+            status="trialing",
+            current_period_start=datetime.now(timezone.utc),
+            current_period_end=datetime.now(timezone.utc) + timedelta(days=TRIAL_DAYS),
+        )
+        db.add(sub)
+        await db.commit()
+        await db.refresh(sub)
+        return sub
+
+    @staticmethod
+    async def create_checkout_session(
+        db: AsyncSession,
+        account: Account,
+        plan: str,
+        seats: int,
+        billing_interval: str,
+        success_url: str,
+        cancel_url: str,
+    ) -> str:
+        """Create a Stripe Checkout Session for subscription purchase. If the
+        account currently has a trialing subscription with time remaining, that
+        trial end is preserved on the new Stripe subscription so the user
+        isn't charged early."""
+        if not settings.stripe_enabled:
+            raise RuntimeError("Stripe not configured")
+        stripe.api_key = settings.STRIPE_SECRET_KEY
+
+        plan_billing = (await db.execute(
+            select(PlanBilling).where(PlanBilling.plan == plan)
+        )).scalar_one_or_none()
+        if plan_billing is None:
+            raise ValueError(f"Unknown plan: {plan}")
+        price_id = (
+            plan_billing.stripe_monthly_price_id if billing_interval == "monthly"
+            else plan_billing.stripe_annual_price_id
+        )
+        if price_id is None:
+            raise RuntimeError(
+                f"Plan '{plan}' has no Stripe price for {billing_interval}"
+            )
+
+        if account.stripe_customer_id is None:
+            customer = stripe.Customer.create(
+                email=None,
+                metadata={"account_id": str(account.id)},
+            )
+            account.stripe_customer_id = customer.id
+            await db.commit()
+
+        sub = (await db.execute(
+            select(Subscription).where(Subscription.account_id == account.id)
+        )).scalar_one_or_none()
+        subscription_data = {}
+        if (
+            sub
+            and sub.status == "trialing"
+            and sub.current_period_end
+            and sub.current_period_end > datetime.now(timezone.utc)
+        ):
+            subscription_data["trial_end"] = int(sub.current_period_end.timestamp())
+
+        session = stripe.checkout.Session.create(
+            customer=account.stripe_customer_id,
+            line_items=[{"price": price_id, "quantity": seats}],
+            mode="subscription",
+            subscription_data=subscription_data or None,
+            success_url=success_url,
+            cancel_url=cancel_url,
+            allow_promotion_codes=False,
+        )
+        return session.url
+
+    @staticmethod
+    async def get_billing_state(db: AsyncSession, account):
+        """Aggregate Subscription + PlanLimits + PlanBilling + resolved feature
+        flags for the account."""
+        from app.models.plan_limits import PlanLimits
+        from app.models.plan_billing import PlanBilling
+        from app.models.feature_flag import (
+            FeatureFlag, PlanFeatureDefault, AccountFeatureOverride,
+        )
+
+        sub = (await db.execute(
+            select(Subscription).where(Subscription.account_id == account.id)
+        )).scalar_one_or_none()
+        if sub is None:
+            from fastapi import HTTPException
+            raise HTTPException(status_code=404, detail="No subscription for account")
+
+        pl = (await db.execute(
+            select(PlanLimits).where(PlanLimits.plan == sub.plan)
+        )).scalar_one_or_none()
+        pb = (await db.execute(
+            select(PlanBilling).where(PlanBilling.plan == sub.plan)
+        )).scalar_one_or_none()
+
+        # Resolved feature flags: plan defaults overridden by account overrides
+        defaults = (await db.execute(
+            select(PlanFeatureDefault, FeatureFlag)
+            .join(FeatureFlag, PlanFeatureDefault.flag_id == FeatureFlag.id)
+            .where(PlanFeatureDefault.plan == sub.plan)
+        )).all()
+        resolved = {flag.flag_key: pfd.enabled for pfd, flag in defaults}
+        overrides = (await db.execute(
+            select(AccountFeatureOverride, FeatureFlag)
+            .join(FeatureFlag, AccountFeatureOverride.flag_id == FeatureFlag.id)
+            .where(AccountFeatureOverride.account_id == account.id)
+        )).all()
+        for ovr, flag in overrides:
+            resolved[flag.flag_key] = ovr.enabled
+
+        return {
+            "subscription": {
+                "status": sub.status,
+                "plan": sub.plan,
+                "current_period_start": sub.current_period_start,
+                "current_period_end": sub.current_period_end,
+                "cancel_at_period_end": sub.cancel_at_period_end,
+                "seat_limit": sub.seat_limit,
+                "has_pro_entitlement": sub.has_pro_entitlement,
+                "is_paid": sub.is_paid,
+            },
+            "plan_billing": pb,
+            "plan_limits": _plan_limits_to_dict(pl) if pl else {},
+            "enabled_features": resolved,
+        }
+
+    @staticmethod
+    async def apply_subscription_event(
+        db: AsyncSession, event_id: str, event_type: str, payload: dict
+    ) -> bool:
+        """Idempotent. Returns True if the event was applied; False if it had
+        already been processed (idempotent ack). The webhook handler returns 200
+        either way."""
+        try:
+            db.add(StripeEvent(
+                id=event_id,
+                event_type=event_type,
+                payload_excerpt=_excerpt(payload),
+            ))
+            await db.commit()
+        except IntegrityError:
+            await db.rollback()
+            return False
+
+        if event_type == "checkout.session.completed":
+            await _handle_checkout_completed(db, payload)
+        elif event_type == "customer.subscription.updated":
+            await _handle_subscription_updated(db, payload)
+        elif event_type == "customer.subscription.deleted":
+            await _handle_subscription_deleted(db, payload)
+        elif event_type == "invoice.payment_failed":
+            await _handle_payment_failed(db, payload)
+        elif event_type == "invoice.payment_succeeded":
+            await _handle_payment_succeeded(db, payload)
+        return True
+
+
+def _plan_limits_to_dict(pl) -> dict:
+    return {c.name: getattr(pl, c.name) for c in pl.__table__.columns}
+
+
+def _excerpt(payload: dict) -> dict:
+    obj = payload.get("data", {}).get("object", {})
+    return {
+        "object_id": obj.get("id"),
+        "customer": obj.get("customer"),
+        "subscription": obj.get("subscription"),
+        "status": obj.get("status"),
+    }
+
+
+async def _handle_checkout_completed(db: AsyncSession, payload: dict):
+    obj = payload["data"]["object"]
+    customer_id = obj["customer"]
+    subscription_id = obj["subscription"]
+
+    account = (await db.execute(
+        select(Account).where(Account.stripe_customer_id == customer_id)
+    )).scalar_one_or_none()
+    if account is None:
+        return
+
+    sub = (await db.execute(
+        select(Subscription).where(Subscription.account_id == account.id)
+    )).scalar_one_or_none()
+    if sub is None:
+        return
+
+    stripe.api_key = settings.STRIPE_SECRET_KEY
+    stripe_sub = stripe.Subscription.retrieve(subscription_id)
+    sub.stripe_subscription_id = subscription_id
+    sub.stripe_price_id = stripe_sub["items"]["data"][0]["price"]["id"]
+    sub.status = "active"
+    sub.current_period_start = datetime.fromtimestamp(stripe_sub["current_period_start"], tz=timezone.utc)
+    sub.current_period_end = datetime.fromtimestamp(stripe_sub["current_period_end"], tz=timezone.utc)
+    sub.seat_limit = stripe_sub["items"]["data"][0]["quantity"]
+    pb = (await db.execute(
+        select(PlanBilling).where(
+            (PlanBilling.stripe_monthly_price_id == sub.stripe_price_id) |
+            (PlanBilling.stripe_annual_price_id == sub.stripe_price_id)
+        )
+    )).scalar_one_or_none()
+    if pb is not None:
+        sub.plan = pb.plan
+    await db.commit()
+
+
+async def _handle_subscription_updated(db: AsyncSession, payload: dict):
+    obj = payload["data"]["object"]
+    sub = (await db.execute(
+        select(Subscription).where(Subscription.stripe_subscription_id == obj["id"])
+    )).scalar_one_or_none()
+    if sub is None:
+        return
+    sub.status = obj["status"]
+    sub.current_period_start = datetime.fromtimestamp(obj["current_period_start"], tz=timezone.utc)
+    sub.current_period_end = datetime.fromtimestamp(obj["current_period_end"], tz=timezone.utc)
+    sub.cancel_at_period_end = obj.get("cancel_at_period_end", False)
+    sub.seat_limit = obj["items"]["data"][0]["quantity"]
+    await db.commit()
+
+
+async def _handle_subscription_deleted(db: AsyncSession, payload: dict):
+    obj = payload["data"]["object"]
+    sub = (await db.execute(
+        select(Subscription).where(Subscription.stripe_subscription_id == obj["id"])
+    )).scalar_one_or_none()
+    if sub is None:
+        return
+    sub.status = "canceled"
+    await db.commit()
+
+
+async def _handle_payment_failed(db: AsyncSession, payload: dict):
+    obj = payload["data"]["object"]
+    subscription_id = obj.get("subscription")
+    if not subscription_id:
+        return
+    sub = (await db.execute(
+        select(Subscription).where(Subscription.stripe_subscription_id == subscription_id)
+    )).scalar_one_or_none()
+    if sub is None:
+        return
+    sub.status = "past_due"
+    await db.commit()
+
+
+async def _handle_payment_succeeded(db: AsyncSession, payload: dict):
+    obj = payload["data"]["object"]
+    subscription_id = obj.get("subscription")
+    if not subscription_id:
+        return
+    sub = (await db.execute(
+        select(Subscription).where(Subscription.stripe_subscription_id == subscription_id)
+    )).scalar_one_or_none()
+    if sub is None:
+        return
+    if sub.status == "past_due":
+        sub.status = "active"
+        await db.commit()

backend/app/services/escalation_package_generator.py

@@ -63,6 +63,9 @@ the active suggested fix, as given in the input bundle under "Outcome status":>
 provided. State that it did not resolve the issue.
 - applied_partial: Include the fix as a partially tried path. Include partial \
 notes if provided. Indicate it was not fully completed or not verified.
+- applied_pending: List the fix as applied but awaiting verification. Include \
+the pending reason if provided. Make it clear the next engineer should follow \
+up to confirm it worked.
 - applied_success: Note that the fix was applied and verified but escalation \
 is still needed for another reason (unusual — reflect this accurately).
 - dismissed: Do not mention the fix as a tried path; it was only considered.
@@ -80,6 +83,8 @@ symptoms are still being narrowed."
 - applied_failed or dismissed: Say the proposed fix did not hold or was set \
 aside. State any remaining uncertainty.
 - applied_partial: Note the partial application and what remains open.
+- applied_pending: Note that the fix is in place but unverified. Reference the \
+pending reason. Frame this as the leading hypothesis pending confirmation.
 - applied_success: Unusual in an escalate path — state the fix resolved the \
 original symptom but a new or related issue requires escalation.
 
@@ -92,6 +97,8 @@ accordingly — e.g. suggest alternatives or deeper investigation paths, \
 drawing on the failure reason if provided. \
 If the fix is partially applied (applied_partial), the first step is typically \
 to complete or verify it. \
+If the fix is pending verification (applied_pending), the first step is \
+typically to confirm whether the fix held — reference what was being waited on. \
 If the fix is still proposed (no outcome), the first step is to try it if \
 confidence is high (>80%).>
 
@@ -299,6 +306,8 @@ class EscalationPackageGeneratorService:
                 lines.append(f"Verified at: {active_fix.verified_at.isoformat()}")
             if active_fix.partial_notes:
                 lines.append(f"Partial notes: {active_fix.partial_notes}")
+            if active_fix.pending_reason:
+                lines.append(f"Pending reason: {active_fix.pending_reason}")
             if active_fix.failure_reason:
                 lines.append(f"Failure reason: {active_fix.failure_reason}")
 

backend/app/services/flowpilot_engine.py

@@ -632,8 +632,10 @@ async def pickup_session(
         allow_team_access=True, team_id=team_id,
     )
 
-    if session.status != "requesting_escalation":
-        raise ValueError(f"Session is {session.status}, not requesting_escalation")
+    if session.status not in ("requesting_escalation", "escalated"):
+        raise ValueError(
+            f"Session is {session.status}, not in an escalated state"
+        )
 
     # Can't pick up your own session
     if session.user_id == user_id:
@@ -911,6 +913,41 @@ async def generate_status_update(
     """Generate a status update for ticket notes, client communication, or email draft."""
     session = await _load_session(session_id, user_id, db)
 
+    # For escalation/ticket_notes, return the pre-generated handoff prose immediately
+    # if enrich_escalation_async has already populated it. This eliminates the
+    # redundant Sonnet re-summarization on every "Ticket Notes" click.
+    if request.context == "escalation" and request.audience == "ticket_notes":
+        from app.models.session_handoff import SessionHandoff
+
+        handoff_q = await db.execute(
+            select(SessionHandoff)
+            .where(
+                SessionHandoff.session_id == session_id,
+                SessionHandoff.intent == "escalate",
+            )
+            .order_by(SessionHandoff.created_at.desc())
+            .limit(1)
+        )
+        escalation_handoff = handoff_q.scalar_one_or_none()
+        saved_data = (
+            escalation_handoff.ai_assessment_data or {}
+        ) if escalation_handoff else {}
+        prose = saved_data.get("summary_prose") or (
+            escalation_handoff.ai_assessment if escalation_handoff else None
+        )
+        if prose:
+            return StatusUpdateResponse(
+                content=prose,
+                audience=request.audience,
+                length=request.length,
+                context=request.context,
+                session_status=session.status,
+                steps_completed=session.step_count or 0,
+                time_spent_display=None,
+                client_name=None,
+                generated_at=datetime.now(timezone.utc),
+            )
+
     # Build conversation summary from session steps
     steps_summary = []
     for step in sorted(session.steps, key=lambda s: s.step_order):

backend/app/services/handoff_manager.py

@@ -3,22 +3,65 @@
 Creates handoff snapshots, AI assessments (for escalations), claim workflow,
 and queue queries. Dual-writes to ai_sessions.escalation_package for
 backward compatibility with the existing escalation queue.
+
+For intent='escalate', `create_handoff` also runs the legacy enrichment
+that the deprecated `/escalate` endpoint used to do directly: setting
+`escalated_to_id`, building the AI-enhanced escalation_package (Sonnet),
+and recording escalation_reason. `finalize_escalation` then generates the
+SessionDocumentation and pushes to PSA. `dispatch_escalation_notifications`
+fans out the bell-icon AppNotification + external channels (Slack/Teams)
+on top of per-user emails. The `/escalate` endpoint is now a thin shim
+calling these in sequence.
 """
+import asyncio
+import json
 import logging
 from datetime import datetime, timezone
 from typing import Any
-from uuid import UUID
+from uuid import UUID, uuid4
 
-from sqlalchemy import select
+from sqlalchemy import select, update
 from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import selectinload
 
+from app.core.ai_provider import get_ai_provider
+from app.core.config import settings
+from app.core.email import EmailService
+from app.core.escalation_bus import bus as escalation_bus
 from app.models.ai_session import AISession
 from app.models.session_branch import SessionBranch
 from app.models.session_handoff import SessionHandoff
+from app.models.user import User
+from app.schemas.ai_session import SessionDocumentation
+from app.services.notification_service import notify
 
 logger = logging.getLogger(__name__)
 
 
+class HandoffAlreadyClaimedError(Exception):
+    """Raised when a senior tries to claim a handoff another senior already won.
+
+    Carries the winning claimer's id, display name, and claim timestamp so the
+    API layer can surface a "Already claimed by {name} {time_ago}" toast on
+    the losing client. The race story is the locked design — without this
+    exception the endpoint would silently overwrite `claimed_by` and both
+    seniors would think they own the session.
+    """
+
+    def __init__(
+        self,
+        claimed_by_id: UUID,
+        claimed_by_name: str,
+        claimed_at: datetime,
+    ) -> None:
+        super().__init__(
+            f"Handoff already claimed by {claimed_by_name} at {claimed_at.isoformat()}"
+        )
+        self.claimed_by_id = claimed_by_id
+        self.claimed_by_name = claimed_by_name
+        self.claimed_at = claimed_at
+
+
 class HandoffManager:
     """Unified park/escalate handoff management."""
 
@@ -32,37 +75,71 @@ class HandoffManager:
         engineer_notes: str | None,
         user_id: UUID,
         priority: str = "normal",
+        target_user_id: UUID | None = None,
     ) -> SessionHandoff:
         """Create a handoff (park or escalate).
 
         Generates snapshot, updates session status, dual-writes to
         escalation_package for backward compat.
+
+        For intent='escalate' also: sets `session.escalation_reason` and
+        optionally `session.escalated_to_id`, builds the AI-enhanced
+        escalation package (the rich one the legacy `/escalate` path used
+        to produce), and merges the handoff metadata into it. Self-targeting
+        is rejected with ValueError, matching legacy behavior.
         """
+        user_id = UUID(str(user_id))
+        if target_user_id:
+            target_user_id = UUID(str(target_user_id))
+
+        # Eager-load steps + user — _build_escalation_package_enhanced and
+        # finalize_escalation iterate over session.steps to compose the
+        # legacy enriched package and the SessionDocumentation, and the
+        # notify() dispatcher reads session.user.name. Without selectinload
+        # the async session raises MissingGreenlet on attribute access.
         result = await self.db.execute(
-            select(AISession).where(AISession.id == session_id)
+            select(AISession)
+            .options(
+                selectinload(AISession.steps),
+                selectinload(AISession.user),
+            )
+            .where(AISession.id == session_id)
         )
         session = result.scalar_one_or_none()
         if not session:
             raise ValueError(f"Session {session_id} not found")
 
-        # Generate snapshot
+        if intent == "escalate":
+            if target_user_id and target_user_id == user_id:
+                raise ValueError(
+                    "Cannot escalate a session to yourself. Use pause instead."
+                )
+            if session.status not in ("active", "paused"):
+                raise ValueError(
+                    f"Cannot escalate session in status: {session.status}"
+                )
+
+        # Generate snapshot — fast, no AI calls.
         snapshot = await self._generate_snapshot(session)
 
-        # Generate AI assessment for escalations
-        ai_assessment = None
-        ai_assessment_data = None
-        if intent == "escalate":
-            ai_assessment, ai_assessment_data = await self._generate_ai_assessment(session)
-
+        # AI enrichment (assessment + enhanced escalation_package) is now
+        # deferred to a background task scheduled by the endpoint after
+        # commit — both calls hit Sonnet and together can take 15-25s,
+        # which is too long to block the click path. The handoff row lands
+        # immediately with `ai_assessment=None`; the magic-moment screen
+        # shows "Assessment still computing" until enrich_async finishes
+        # and the senior refreshes (or, eventually, polls).
+        handoff_id = uuid4()
         handoff = SessionHandoff(
+            id=handoff_id,
             session_id=session_id,
             account_id=session.account_id,
             handed_off_by=user_id,
             intent=intent,
             source_branch_id=session.active_branch_id,
             snapshot=snapshot,
-            ai_assessment=ai_assessment,
-            ai_assessment_data=ai_assessment_data,
+            ai_assessment=None,
+            ai_assessment_data=None,
             engineer_notes=engineer_notes,
             priority=priority,
         )
@@ -73,20 +150,248 @@ class HandoffManager:
             session.status = "paused"
         elif intent == "escalate":
             session.status = "escalated"
+            session.escalation_reason = engineer_notes
+            if target_user_id:
+                session.escalated_to_id = target_user_id
 
         session.handoff_count = (session.handoff_count or 0) + 1
 
-        # Dual-write for backward compat
+        # Dual-write the minimal escalation_package shape now. The async
+        # enrichment task overwrites this with the AI-enhanced shape
+        # (`steps_tried`, `remaining_hypotheses`, etc.) when it completes —
+        # consumers that read these fields (PSA writeback, legacy
+        # SessionBriefing) tolerate either shape.
         session.escalation_package = {
             "snapshot": snapshot,
             "intent": intent,
             "engineer_notes": engineer_notes,
-            "handoff_id": str(handoff.id),
+            "handoff_id": str(handoff_id),
         }
 
         await self.db.flush()
         return handoff
 
+    async def finalize_escalation(
+        self,
+        handoff: SessionHandoff,
+        session: AISession,
+        user_id: UUID,
+    ) -> tuple[SessionDocumentation | None, dict[str, Any]]:
+        """Post-create enrichment for intent='escalate' handoffs.
+
+        Generates the SessionDocumentation + pushes documentation to PSA if
+        a ticket is linked. Returns (documentation, psa_result) so the
+        legacy `/escalate` shim can map back to SessionCloseResponse. Safe
+        to call only when handoff.intent == 'escalate' — for park, returns
+        a no-op no-PSA dict.
+        """
+        if handoff.intent != "escalate":
+            return None, {
+                "psa_push_status": "no_psa",
+                "psa_push_error": None,
+                "member_mapping_warning": None,
+            }
+
+        # Lazy import to avoid circular dependency: flowpilot_engine imports
+        # plenty of services at module load time and we don't want
+        # handoff_manager pulled into that graph at import.
+        from app.services.flowpilot_engine import (
+            _generate_documentation,
+            _push_to_psa,
+        )
+
+        documentation = _generate_documentation(session)
+        psa_result = await _push_to_psa(session, user_id, self.db)
+
+        # Bell-icon AppNotification rows + external account-level channels
+        # (Slack/Teams webhooks, shared escalations inboxes). This is the
+        # `notify()` call the legacy /escalate path used to make directly,
+        # and it has to happen BEFORE the endpoint commits so the
+        # AppNotification rows land atomically with the handoff. Per-user
+        # emails come after commit in dispatch_escalation_notifications —
+        # those are pure IO with no persistent state.
+        try:
+            engineer_user = (
+                await self.db.execute(
+                    select(User).where(User.id == user_id)
+                )
+            ).scalar_one_or_none()
+            engineer_name = (
+                engineer_user.name
+                if engineer_user and engineer_user.name
+                else "Unknown"
+            )
+            target_user_ids = (
+                [session.escalated_to_id] if session.escalated_to_id else None
+            )
+            await notify(
+                "session.escalated",
+                handoff.account_id,
+                {
+                    "session_id": str(handoff.session_id),
+                    "engineer_name": engineer_name,
+                    "escalation_reason": handoff.engineer_notes or "",
+                    "problem_summary": session.problem_summary or "N/A",
+                    # Surface the PSA ticket id in the bell-icon title so two
+                    # similarly-worded escalations are still distinguishable
+                    # at a glance.
+                    "psa_ticket_id": session.psa_ticket_id,
+                },
+                self.db,
+                target_user_ids=target_user_ids,
+            )
+        except Exception:
+            logger.exception(
+                "notify() dispatch failed for handoff %s", handoff.id
+            )
+
+        return documentation, psa_result
+
+    async def _build_enhanced_escalation_package(
+        self,
+        session: AISession,
+        user_id: UUID,
+    ) -> dict[str, Any]:
+        """Lazy wrapper around the legacy enhanced-package builder.
+
+        The builder lives in flowpilot_engine; we only need it for the
+        escalate path. Failures are caught here so handoff creation never
+        depends on the optional Sonnet enrichment — return the minimal
+        shape on failure.
+        """
+        try:
+            from app.services.flowpilot_engine import (
+                _build_escalation_package_enhanced,
+            )
+            return await _build_escalation_package_enhanced(session, user_id)
+        except Exception:
+            logger.exception(
+                "Enhanced escalation package build failed for session %s; "
+                "falling back to minimal package",
+                session.id,
+            )
+            return {}
+
+
+    async def dispatch_escalation_notifications(
+        self, handoff: SessionHandoff
+    ) -> int:
+        """Email engineer-or-admin users in the account about a new escalation.
+
+        Call this AFTER `db.commit()` has succeeded — sending email for a
+        rolled-back handoff is the kind of trust-erosion bug that makes pilot
+        customers stop trusting the tool. Returns the number of recipients
+        successfully emailed (best-effort, not authoritative).
+
+        Failures are logged but never raise: the wedge demo's reliability
+        story is "handoff creation always succeeds; notification is best-effort,"
+        not "handoff creation depends on the email service being up." This is
+        the graceful-degradation regression the eng + codex reviews both
+        flagged as critical.
+
+        Per-channel delivery records (Codex correction on the dead
+        `notification_sent` boolean) are a v1.x story — for now the
+        application logs are the audit trail.
+        """
+        if handoff.intent != "escalate":
+            return 0
+
+        # Publish to the in-memory bus first so connected senior-tech inboxes
+        # see the new card slide in within ~1s of escalate. This path is
+        # fire-and-forget (no IO, just memory) so it can sit ahead of the
+        # email fan-out.
+        try:
+            await escalation_bus.publish(
+                handoff.account_id,
+                {
+                    "type": "handoff_created",
+                    "handoff_id": str(handoff.id),
+                    "session_id": str(handoff.session_id),
+                    "priority": handoff.priority,
+                    "engineer_notes": handoff.engineer_notes or "",
+                    "created_at": handoff.created_at.isoformat()
+                    if handoff.created_at
+                    else None,
+                },
+            )
+        except Exception:
+            logger.exception(
+                "EscalationBus publish failed for handoff %s", handoff.id
+            )
+
+        try:
+            recipients = (
+                await self.db.execute(
+                    select(User).where(
+                        User.account_id == handoff.account_id,
+                        User.id != handoff.handed_off_by,
+                        User.account_role.in_(("owner", "admin", "engineer")),
+                        User.is_active.is_(True),
+                        User.deleted_at.is_(None),
+                    )
+                )
+            ).scalars().all()
+
+            if not recipients:
+                logger.info(
+                    "No notification recipients for handoff %s in account %s",
+                    handoff.id,
+                    handoff.account_id,
+                )
+                return 0
+
+            # Pull session for the email subject. Fall back to a generic title
+            # if the session is gone (e.g. cascade delete mid-dispatch).
+            session_result = await self.db.execute(
+                select(AISession).where(AISession.id == handoff.session_id)
+            )
+            session = session_result.scalar_one_or_none()
+            problem = (
+                session.problem_summary if session and session.problem_summary
+                else "an active session"
+            )
+
+            title = f"New escalation: {problem}"
+            notes = (handoff.engineer_notes or "").strip()
+            body = (
+                "A teammate has escalated a session and is asking for help.\n\n"
+                f"Reason: {notes if notes else 'No reason provided.'}\n"
+                f"Priority: {handoff.priority}"
+            )
+            link_url = (
+                f"{settings.FRONTEND_URL.rstrip('/')}/escalations"
+                if settings.FRONTEND_URL
+                else None
+            )
+
+            results = await asyncio.gather(
+                *[
+                    EmailService.send_notification_email(
+                        to_email=r.email,
+                        title=title,
+                        body=body,
+                        link_url=link_url,
+                    )
+                    for r in recipients
+                ],
+                return_exceptions=True,
+            )
+            sent = sum(1 for r in results if r is True)
+            logger.info(
+                "Escalation notifications dispatched for handoff %s: %d/%d recipients",
+                handoff.id,
+                sent,
+                len(recipients),
+            )
+            return sent
+
+        except Exception:
+            logger.exception(
+                "Escalation notification dispatch failed for handoff %s",
+                handoff.id,
+            )
+            return 0
+
     async def _generate_snapshot(self, session: AISession) -> dict[str, Any]:
         """Generate a snapshot of the session state at handoff time."""
         snapshot: dict[str, Any] = {
@@ -125,16 +430,56 @@ class HandoffManager:
         handoff_id: UUID,
         claiming_user_id: UUID,
     ) -> SessionHandoff:
-        """Claim a handed-off session."""
+        """Claim a handed-off session.
+
+        If the handoff was already claimed by a *different* user (the race
+        story: two seniors clicking Pick Up simultaneously), raise
+        `HandoffAlreadyClaimedError` with the winning claimer's details so
+        the API can return 409 with the data the loser's toast needs. A
+        re-claim by the same user is idempotent.
+        """
+        claiming_user_id = UUID(str(claiming_user_id))
+        claimed_at = datetime.now(timezone.utc)
+
+        update_result = await self.db.execute(
+            update(SessionHandoff)
+            .where(
+                SessionHandoff.id == handoff_id,
+                SessionHandoff.claimed_by.is_(None),
+                SessionHandoff.handed_off_by != claiming_user_id,
+            )
+            .values(claimed_by=claiming_user_id, claimed_at=claimed_at)
+            .returning(SessionHandoff.id)
+        )
+        claimed_now = update_result.scalar_one_or_none() is not None
+
         result = await self.db.execute(
-            select(SessionHandoff).where(SessionHandoff.id == handoff_id)
+            select(SessionHandoff)
+            .options(
+                selectinload(SessionHandoff.claimed_by_user),
+                selectinload(SessionHandoff.handed_off_by_user),
+            )
+            .where(SessionHandoff.id == handoff_id)
         )
         handoff = result.scalar_one_or_none()
         if not handoff:
             raise ValueError(f"Handoff {handoff_id} not found")
 
-        handoff.claimed_by = claiming_user_id
-        handoff.claimed_at = datetime.now(timezone.utc)
+        handed_off_by = UUID(str(handoff.handed_off_by))
+        claimed_by = (
+            UUID(str(handoff.claimed_by)) if handoff.claimed_by is not None else None
+        )
+
+        if handed_off_by == claiming_user_id:
+            raise PermissionError("Cannot claim your own handoff")
+
+        if not claimed_now and claimed_by != claiming_user_id:
+            claimer = handoff.claimed_by_user
+            raise HandoffAlreadyClaimedError(
+                claimed_by_id=claimed_by,
+                claimed_by_name=claimer.name if claimer else "another engineer",
+                claimed_at=handoff.claimed_at or datetime.now(timezone.utc),
+            )
 
         # Reactivate session
         session_result = await self.db.execute(
@@ -149,43 +494,111 @@ class HandoffManager:
         await self.db.flush()
         return handoff
 
-    async def _generate_ai_assessment(
+    async def _generate_handoff_summary(
         self, session: AISession
-    ) -> tuple[str | None, dict[str, Any] | None]:
-        """Generate AI diagnostic assessment for escalation handoffs."""
+    ) -> dict[str, Any] | None:
+        """Single structured AI call for the escalation magic-moment screen.
+
+        Returns a dict with summary_prose, what_we_know, likely_cause,
+        suggested_steps, and confidence. Returns None on timeout or error.
+        Replaces the old _generate_ai_assessment + _generate_ai_assessment_with_timeout
+        pair, which returned freeform prose with no usable structured fields.
+        """
+        timeout = settings.ESCALATION_AI_ASSESSMENT_TIMEOUT_SECONDS
         try:
-            from app.services.assistant_chat_service import _call_ai
-
-            context = f"Problem: {session.problem_summary or 'Unknown'}\nDomain: {session.problem_domain or 'Unknown'}"
-            msgs = session.conversation_messages or []
-            # Include last 10 messages for context
-            recent = "\n".join(
-                f"[{m.get('role', '?')}]: {m.get('content', '')[:200]}"
-                for m in msgs[-10:]
+            return await asyncio.wait_for(
+                self._generate_handoff_summary_inner(session),
+                timeout=timeout,
             )
-
-            assessment_text, _, _ = await _call_ai(
-                system_base="You are a diagnostic assessment generator for MSP escalations.",
-                rag_context="",
-                history=[],
-                new_message=(
-                    f"Generate a brief diagnostic assessment for this escalation.\n"
-                    f"{context}\n\nRecent conversation:\n{recent}\n\n"
-                    f"Return: 1) Most likely cause, 2) Suggested next steps, 3) Confidence (low/medium/high)"
-                ),
-                max_tokens=500,
+        except asyncio.TimeoutError:
+            logger.warning(
+                "Handoff summary timed out after %ss for session %s",
+                timeout,
+                session.id,
             )
-
-            assessment_data = {
-                "likely_cause": "See assessment text",
-                "suggested_steps": [],
-                "confidence": "medium",
-            }
-
-            return assessment_text, assessment_data
+            return None
         except Exception:
-            logger.exception("Failed to generate AI assessment")
-            return None, None
+            logger.exception(
+                "Handoff summary failed for session %s", session.id
+            )
+            return None
+
+    async def _generate_handoff_summary_inner(
+        self, session: AISession
+    ) -> dict[str, Any]:
+        steps = session.steps or []
+        steps_tried = []
+        for step in sorted(steps, key=lambda s: s.step_order):
+            content = step.content or {}
+            text = content.get("text", "").strip()
+            if not text:
+                continue
+            entry = text
+            if step.selected_option:
+                entry += f" → {step.selected_option}"
+            elif step.free_text_input:
+                entry += f" → {step.free_text_input[:100]}"
+            elif step.was_skipped:
+                entry += " (skipped)"
+            steps_tried.append(entry)
+        steps_text = (
+            "\n".join(f"- {s}" for s in steps_tried[:15])
+            or "No diagnostic steps recorded."
+        )
+
+        msgs = session.conversation_messages or []
+        recent_msgs = "\n".join(
+            f"[{m.get('role', '?')}]: {m.get('content', '')[:200]}"
+            for m in msgs[-10:]
+        )
+
+        prompt = (
+            "Generate a structured escalation handoff summary.\n\n"
+            f"Problem: {session.problem_summary or 'Unknown'}\n"
+            f"Domain: {session.problem_domain or 'Unknown'}\n"
+            f"Escalation reason: {session.escalation_reason or 'Not provided'}\n\n"
+            f"Diagnostic steps taken:\n{steps_text}\n\n"
+            f"Recent conversation:\n{recent_msgs}\n\n"
+            "Respond with ONLY a valid JSON object matching this schema exactly:\n"
+            '{"summary_prose": "<2-3 sentences suitable for PSA ticket notes>",\n'
+            ' "what_we_know": ["<confirmed fact 1>", "<confirmed fact 2>"],\n'
+            ' "likely_cause": "<one sentence root cause hypothesis>",\n'
+            ' "suggested_steps": ["<next step 1>", "<next step 2>"],\n'
+            ' "confidence": "<low or medium or high>"}'
+        )
+
+        provider = get_ai_provider(settings.get_model_for_action("escalation_package"))
+        raw, _, _ = await provider.generate_json(
+            system_prompt=(
+                "You are a diagnostic assessment generator for MSP tech support escalations. "
+                "Always respond with valid JSON and nothing else. "
+                "Be concise and factual."
+            ),
+            messages=[{"role": "user", "content": prompt}],
+            max_tokens=700,
+        )
+
+        cleaned = raw.strip()
+        if cleaned.startswith("```"):
+            lines = cleaned.split("\n", 1)
+            cleaned = lines[1] if len(lines) > 1 else cleaned
+            if cleaned.endswith("```"):
+                cleaned = cleaned[:-3].rstrip()
+
+        result = json.loads(cleaned)
+
+        if not isinstance(result.get("suggested_steps"), list):
+            result["suggested_steps"] = []
+        if not isinstance(result.get("what_we_know"), list):
+            result["what_we_know"] = []
+        if result.get("confidence") not in ("low", "medium", "high"):
+            result["confidence"] = "medium"
+        if not isinstance(result.get("summary_prose"), str) or not result.get("summary_prose"):
+            result["summary_prose"] = result.get("likely_cause", "Assessment generated.")
+        if not isinstance(result.get("likely_cause"), str):
+            result["likely_cause"] = ""
+
+        return result
 
     async def generate_briefing(
         self, handoff_id: UUID, claiming_user_id: UUID
@@ -288,3 +701,105 @@ class HandoffManager:
             })
 
         return queue_items
+
+
+async def enrich_escalation_async(handoff_id: UUID, user_id: UUID) -> None:
+    """Run the AI enrichment for an escalation handoff in the background.
+
+    Scheduled by `/escalate` and `/handoff` (intent=escalate) endpoints via
+    FastAPI BackgroundTasks. Opens its own DB session because the request
+    session is closed by the time this runs. Generates:
+
+      1. The legacy AI-enhanced escalation_package (Sonnet, ~5-10s) — saved
+         to `session.escalation_package`, preserving the `intent` /
+         `engineer_notes` / `handoff_id` keys the dual-write set so legacy
+         consumers keep working.
+      2. The diagnostic AI assessment (Sonnet, ~4-15s) — saved to
+         `handoff.ai_assessment` and `handoff.ai_assessment_data`.
+
+    On completion publishes a `handoff_assessment_ready` event on the
+    escalation bus so any connected magic-moment screen can refresh
+    without a manual reload. Failures are logged but never propagated —
+    the click-path-side handoff creation already committed, so worst case
+    the senior sees the "Assessment still computing" placeholder until
+    they refresh manually.
+    """
+    from app.core.database import async_session_maker
+    from app.core.escalation_bus import bus as escalation_bus
+
+    async with async_session_maker() as db:
+        try:
+            result = await db.execute(
+                select(SessionHandoff).where(SessionHandoff.id == handoff_id)
+            )
+            handoff = result.scalar_one_or_none()
+            if not handoff or handoff.intent != "escalate":
+                return
+
+            session_result = await db.execute(
+                select(AISession)
+                .options(selectinload(AISession.steps), selectinload(AISession.user))
+                .where(AISession.id == handoff.session_id)
+            )
+            session = session_result.scalar_one_or_none()
+            if not session:
+                logger.warning(
+                    "enrich_escalation_async: session %s gone for handoff %s",
+                    handoff.session_id,
+                    handoff_id,
+                )
+                return
+
+            manager = HandoffManager(db)
+
+            # Single consolidated AI call — replaces the old
+            # _generate_ai_assessment + _build_enhanced_escalation_package pair.
+            try:
+                summary = await manager._generate_handoff_summary(session)
+                if summary:
+                    # ai_assessment (text) holds the PSA prose for backward compat
+                    # (push_to_psa reads it; generate_status_update falls back to it).
+                    handoff.ai_assessment = summary.get("summary_prose")
+                    handoff.ai_assessment_data = summary
+                    # Keep suggested_next_steps in escalation_package so
+                    # psa_documentation_service can read it without a handoff join.
+                    existing_pkg = (
+                        session.escalation_package
+                        if isinstance(session.escalation_package, dict)
+                        else {}
+                    )
+                    session.escalation_package = {
+                        **existing_pkg,
+                        "suggested_next_steps": summary.get("suggested_steps", []),
+                    }
+            except Exception:
+                logger.exception(
+                    "enrich_escalation_async: summary generation failed for handoff %s",
+                    handoff_id,
+                )
+
+            await db.commit()
+
+            try:
+                await escalation_bus.publish(
+                    handoff.account_id,
+                    {
+                        "type": "handoff_assessment_ready",
+                        "handoff_id": str(handoff.id),
+                        "session_id": str(handoff.session_id),
+                        "has_assessment": handoff.ai_assessment_data is not None,
+                    },
+                )
+            except Exception:
+                logger.exception(
+                    "enrich_escalation_async: bus publish failed for handoff %s",
+                    handoff_id,
+                )
+        except Exception:
+            logger.exception(
+                "enrich_escalation_async failed for handoff %s", handoff_id
+            )
+            try:
+                await db.rollback()
+            except Exception:
+                pass

backend/app/services/notification_service.py

@@ -371,13 +371,35 @@ async def _send_teams_message(
 def _build_notification_title(event: str, payload: dict[str, Any]) -> str:
     """Human-readable title per event type."""
     titles = {
-        "session.escalated": "Session escalated by {engineer_name}",
+        # Distinguishability matters in the bell panel: with a generic title
+        # ("Session escalated by Jane") two different escalations from the
+        # same junior look like a duplicate notification. Including a short
+        # problem snippet (and ticket number if present) lets the senior
+        # tell them apart at a glance.
+        "session.escalated": "Escalation from {engineer_name}{ticket_suffix}: {problem_snippet}",
         "session.high_priority": "High-priority session started: {ticket_number}",
         "proposal.pending": "New flow proposal: {title}",
         "proposal.approved": "Flow proposal approved: {title}",
         "knowledge_gap.detected": "Knowledge gap detected: {gap_type}",
         "test": "Test Notification from ResolutionFlow",
     }
+
+    # Build the escalation-specific derived fields. Done here rather than at
+    # the call site so every dispatch path (legacy /escalate shim, /handoff,
+    # any future entry point) gets consistent formatting without each one
+    # having to repeat the snippet logic.
+    if event == "session.escalated":
+        problem = (payload.get("problem_summary") or "").strip()
+        if not problem or problem.upper() == "N/A":
+            problem_snippet = "(no summary provided)"
+        elif len(problem) > 70:
+            problem_snippet = problem[:67].rstrip() + "…"
+        else:
+            problem_snippet = problem
+        ticket = payload.get("psa_ticket_id") or payload.get("ticket_number")
+        ticket_suffix = f" · #{ticket}" if ticket else ""
+        payload = {**payload, "problem_snippet": problem_snippet, "ticket_suffix": ticket_suffix}
+
     template = titles.get(event, f"Notification: {event}")
     try:
         return template.format(**payload)
@@ -405,7 +427,12 @@ def _build_notification_body(event: str, payload: dict[str, Any]) -> str:
 def _build_notification_link(event: str, payload: dict[str, Any]) -> Optional[str]:
     """In-app link per event type. Returns path (no host)."""
     links: dict[str, str] = {
-        "session.escalated": "/pilot/{session_id}",
+        # ?pickup=true triggers the senior-tech handoff/pickup flow on the
+        # session page (magic-moment screen for handoff-based escalations,
+        # legacy SessionBriefing for `requesting_escalation` sessions).
+        # Without it the senior lands on a session-detail GET they can't
+        # access pre-pickup, which the user perceives as a dead notification.
+        "session.escalated": "/pilot/{session_id}?pickup=true",
         "session.high_priority": "/pilot/{session_id}",
         "proposal.pending": "/review-queue",
         "proposal.approved": "/review-queue",

backend/app/services/oauth_providers.py

@@ -0,0 +1,71 @@
+"""OAuth provider helpers. Each provider exposes:
+- exchange_code(code, redirect_uri) -> OAuthProfile
+"""
+from dataclasses import dataclass
+
+import httpx
+from app.core.config import settings
+
+
+@dataclass
+class OAuthProfile:
+    provider_subject: str
+    email: str
+    name: str
+
+
+async def google_exchange_code(code: str, redirect_uri: str) -> OAuthProfile:
+    async with httpx.AsyncClient(timeout=10) as cli:
+        token_response = await cli.post(
+            "https://oauth2.googleapis.com/token",
+            data={
+                "code": code,
+                "client_id": settings.GOOGLE_CLIENT_ID,
+                "client_secret": settings.GOOGLE_CLIENT_SECRET,
+                "redirect_uri": redirect_uri,
+                "grant_type": "authorization_code",
+            },
+        )
+        token_response.raise_for_status()
+        access_token = token_response.json()["access_token"]
+
+        userinfo = await cli.get(
+            "https://openidconnect.googleapis.com/v1/userinfo",
+            headers={"Authorization": f"Bearer {access_token}"},
+        )
+        userinfo.raise_for_status()
+        data = userinfo.json()
+        return OAuthProfile(
+            provider_subject=data["sub"],
+            email=data["email"],
+            name=data.get("name") or data["email"].split("@")[0],
+        )
+
+
+async def microsoft_exchange_code(code: str, redirect_uri: str) -> OAuthProfile:
+    async with httpx.AsyncClient(timeout=10) as cli:
+        token_response = await cli.post(
+            "https://login.microsoftonline.com/common/oauth2/v2.0/token",
+            data={
+                "code": code,
+                "client_id": settings.MS_CLIENT_ID,
+                "client_secret": settings.MS_CLIENT_SECRET,
+                "redirect_uri": redirect_uri,
+                "grant_type": "authorization_code",
+                "scope": "openid email profile",
+            },
+        )
+        token_response.raise_for_status()
+        access_token = token_response.json()["access_token"]
+
+        userinfo = await cli.get(
+            "https://graph.microsoft.com/v1.0/me",
+            headers={"Authorization": f"Bearer {access_token}"},
+        )
+        userinfo.raise_for_status()
+        data = userinfo.json()
+        return OAuthProfile(
+            provider_subject=data["id"],
+            email=data.get("mail") or data["userPrincipalName"],
+            name=data.get("displayName") or data["userPrincipalName"].split("@")[0],
+        )

backend/app/services/resolution_note_generator.py

@@ -83,6 +83,10 @@ state means the engineer resolved the issue another way; the note should cover \
 that actual resolution, not just the failed attempt.
 - applied_partial: Note that the fix was partially applied. If partial_notes \
 are provided, include them. Then describe the final resolution path taken.
+- applied_pending: Note that the fix was applied and verification is pending. \
+If pending_reason is provided, include it as the provided waiting reason. \
+Frame the resolution as provisional — the fix is in place but not yet \
+confirmed. Do not write closure language.
 - dismissed: Treat the fix as considered and set aside. Do not center the note \
 on it. Describe the resolution based on what was actually confirmed and done.
 - proposed (no outcome yet): Write "Resolution not yet applied — fix proposed: \
@@ -322,6 +326,8 @@ class ResolutionNoteGeneratorService:
                 lines.append(f"Verified at: {active_fix.verified_at.isoformat()}")
             if active_fix.partial_notes:
                 lines.append(f"Partial notes: {active_fix.partial_notes}")
+            if active_fix.pending_reason:
+                lines.append(f"Pending reason: {active_fix.pending_reason}")
             if active_fix.failure_reason:
                 lines.append(f"Failure reason: {active_fix.failure_reason}")
 

backend/app/services/unified_chat_service.py

@@ -583,10 +583,14 @@ async def send_chat_message(
 
     Returns (ai_content, suggested_flows, session, fork_metadata, actions_data, questions_data).
     """
+    from sqlalchemy import or_
     result = await db.execute(
         select(AISession).where(
             AISession.id == session_id,
-            AISession.user_id == user_id,
+            or_(
+                AISession.user_id == user_id,
+                AISession.escalated_to_id == user_id,
+            ),
             AISession.session_type == "chat",
         )
     )

backend/scripts/seed_test_users.py

@@ -97,7 +97,18 @@ async def main() -> None:
             )
             row = result.first()
             if row:
-                print(f"  [SKIP]  {cfg['email']} already exists")
+                # Backfill email_verified_at for existing rows so older test
+                # users created before this script set the field still bypass
+                # the 7-day verification grace.
+                await conn.execute(
+                    text("""
+                        UPDATE users
+                        SET email_verified_at = COALESCE(email_verified_at, :now)
+                        WHERE email = :email
+                    """),
+                    {"email": cfg["email"], "now": now},
+                )
+                print(f"  [SKIP]  {cfg['email']} already exists (email_verified_at backfilled if null)")
                 if cfg["key"] == "team_admin":
                     team_account_id = row.account_id
                 continue
@@ -130,12 +141,17 @@ async def main() -> None:
 
             # ---- Create User ----
             user_id = uuid.uuid4()
+            # email_verified_at is stamped at seed time so test users bypass the
+            # 7-day verification grace immediately. Without this, fixtures hit
+            # require_verified_email_after_grace once their created_at ages past
+            # 7 days and get walled out of protected routes.
             await conn.execute(
                 text("""
                     INSERT INTO users (id, email, password_hash, name, role, is_super_admin,
-                                       is_team_admin, is_active, account_id, account_role, created_at)
+                                       is_team_admin, is_active, account_id, account_role,
+                                       created_at, email_verified_at)
                     VALUES (:id, :email, :pw, :name, 'engineer', :is_sa, :is_ta, true,
-                            :account_id, :account_role, :now)
+                            :account_id, :account_role, :now, :now)
                 """),
                 {
                     "id": user_id,

backend/tests/conftest.py

@@ -248,13 +248,23 @@ async def client(test_db: AsyncSession):
 
 
 @pytest.fixture
-async def test_user(client):
+async def test_user(client, test_db):
     """
     Create a test user and return their credentials.
 
+    Also seeds a default active Pro Subscription so Pro-guarded routes work
+    in tests. Phase 1 Task 11 added require_active_subscription; without
+    this seed every existing test that hits a Pro router would 402. The
+    register endpoint creates a default `free`/`active` Subscription, so
+    we delete-then-insert to avoid the unique account_id constraint.
+
     Returns:
         dict with email, password, and user_data
     """
+    import uuid
+    from sqlalchemy import delete
+    from app.models.subscription import Subscription
+
     user_data = {
         "email": "test@example.com",
         "password": "TestPassword123!",
@@ -264,6 +274,13 @@ async def test_user(client):
     response = await client.post("/api/v1/auth/register", json=user_data)
     assert response.status_code == 200 or response.status_code == 201
 
+    account_id = uuid.UUID(response.json()["account_id"])
+    await test_db.execute(
+        delete(Subscription).where(Subscription.account_id == account_id)
+    )
+    test_db.add(Subscription(account_id=account_id, plan="pro", status="active"))
+    await test_db.commit()
+
     return {
         "email": user_data["email"],
         "password": user_data["password"],
@@ -346,11 +363,14 @@ async def test_admin(client, test_db):
     Create a test super-admin user.
 
     Registers as engineer (the only role available at registration),
-    then promotes to super_admin directly via the DB session.
+    then promotes to super_admin directly via the DB session. Also
+    seeds a default active Pro Subscription (see test_user docstring).
     """
+    import uuid
     from uuid import UUID as PyUUID
-    from sqlalchemy import select
+    from sqlalchemy import select, delete
     from app.models.user import User
+    from app.models.subscription import Subscription
 
     admin_data = {
         "email": "admin@example.com",
@@ -365,6 +385,12 @@ async def test_admin(client, test_db):
     result = await test_db.execute(select(User).where(User.id == user_id))
     user = result.scalar_one()
     user.is_super_admin = True
+
+    account_id = uuid.UUID(response.json()["account_id"])
+    await test_db.execute(
+        delete(Subscription).where(Subscription.account_id == account_id)
+    )
+    test_db.add(Subscription(account_id=account_id, plan="pro", status="active"))
     await test_db.commit()
 
     return {

backend/tests/test_account_invite_extensions.py

@@ -0,0 +1,180 @@
+import pytest
+from unittest.mock import AsyncMock, patch
+from sqlalchemy import select
+from app.models.account_invite import AccountInvite
+
+
+@pytest.mark.asyncio
+async def test_create_invite_sends_email_and_stamps_email_sent_at(
+    client, test_db, test_user, auth_headers
+):
+    """Regression: today's create_invite does NOT send email. After this task, it MUST."""
+    with patch(
+        "app.core.email.EmailService.send_account_invite_email",
+        new_callable=AsyncMock, return_value=True,
+    ) as mock_send:
+        response = await client.post(
+            "/api/v1/accounts/me/invites",
+            json={"email": "teammate@example.com", "role": "engineer"},
+            headers=auth_headers,
+        )
+    assert response.status_code == 201, response.json()
+    mock_send.assert_called_once()
+    kwargs = mock_send.call_args.kwargs
+    assert kwargs["to_email"] == "teammate@example.com"
+    assert kwargs["role"] == "engineer"
+    assert kwargs["code"]
+
+    invite = (await test_db.execute(
+        select(AccountInvite).where(AccountInvite.email == "teammate@example.com")
+    )).scalar_one()
+    assert invite.email_sent_at is not None
+
+
+@pytest.mark.asyncio
+async def test_create_invite_email_failure_still_creates_row(
+    client, test_db, test_user, auth_headers
+):
+    """When EmailService returns False, the invite row is still created but
+    email_sent_at remains NULL."""
+    with patch(
+        "app.core.email.EmailService.send_account_invite_email",
+        new_callable=AsyncMock, return_value=False,
+    ):
+        response = await client.post(
+            "/api/v1/accounts/me/invites",
+            json={"email": "fail-mail@example.com", "role": "engineer"},
+            headers=auth_headers,
+        )
+    assert response.status_code == 201
+
+    invite = (await test_db.execute(
+        select(AccountInvite).where(AccountInvite.email == "fail-mail@example.com")
+    )).scalar_one()
+    assert invite.email_sent_at is None
+
+
+@pytest.mark.asyncio
+async def test_bulk_invite_creates_n_rows_and_sends_n_emails(
+    client, test_db, test_user, auth_headers
+):
+    with patch(
+        "app.core.email.EmailService.send_account_invite_email",
+        new_callable=AsyncMock, return_value=True,
+    ) as mock_send:
+        response = await client.post(
+            "/api/v1/accounts/me/invites/bulk",
+            json={"invites": [
+                {"email": "a@example.com", "role": "engineer"},
+                {"email": "b@example.com", "role": "engineer"},
+                {"email": "c@example.com", "role": "viewer"},
+            ]},
+            headers=auth_headers,
+        )
+    assert response.status_code == 201, response.json()
+    body = response.json()
+    assert len(body["created"]) == 3
+    assert body["failed"] == []
+    assert mock_send.call_count == 3
+
+
+@pytest.mark.asyncio
+async def test_revoke_invite_sets_revoked_at(client, test_db, test_user, auth_headers):
+    import uuid
+    from datetime import datetime, timezone, timedelta
+    from app.models.account_invite import AccountInvite
+
+    invited_by_id = uuid.UUID(test_user["user_data"]["id"])
+    account_id = uuid.UUID(test_user["user_data"]["account_id"])
+
+    invite = AccountInvite(
+        account_id=account_id,
+        invited_by_id=invited_by_id,
+        email="revoked@example.com",
+        code="REVOKEME01",
+        role="engineer",
+        expires_at=datetime.now(timezone.utc) + timedelta(days=7),
+    )
+    test_db.add(invite)
+    await test_db.commit()
+    invite_id = invite.id
+
+    response = await client.delete(
+        f"/api/v1/accounts/me/invites/{invite_id}",
+        headers=auth_headers,
+    )
+    assert response.status_code == 204
+
+    await test_db.refresh(invite)
+    assert invite.revoked_at is not None
+    assert invite.is_valid is False
+
+
+@pytest.mark.asyncio
+async def test_revoke_invite_idempotent(client, test_db, test_user, auth_headers):
+    import uuid
+    from datetime import datetime, timezone, timedelta
+    from app.models.account_invite import AccountInvite
+
+    invited_by_id = uuid.UUID(test_user["user_data"]["id"])
+    account_id = uuid.UUID(test_user["user_data"]["account_id"])
+
+    invite = AccountInvite(
+        account_id=account_id,
+        invited_by_id=invited_by_id,
+        email="revoked2@example.com",
+        code="REVOKEME02",
+        role="engineer",
+        revoked_at=datetime.now(timezone.utc),
+        expires_at=datetime.now(timezone.utc) + timedelta(days=7),
+    )
+    test_db.add(invite)
+    await test_db.commit()
+    invite_id = invite.id
+
+    response = await client.delete(
+        f"/api/v1/accounts/me/invites/{invite_id}",
+        headers=auth_headers,
+    )
+    assert response.status_code == 204
+
+
+@pytest.mark.asyncio
+async def test_revoke_invite_404_when_not_found(client, test_user, auth_headers):
+    import uuid
+    response = await client.delete(
+        f"/api/v1/accounts/me/invites/{uuid.uuid4()}",
+        headers=auth_headers,
+    )
+    assert response.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_revoke_used_invite_returns_400(
+    client, test_db, test_user, auth_headers
+):
+    import uuid
+    from datetime import datetime, timezone, timedelta
+    from app.models.account_invite import AccountInvite
+
+    invited_by_id = uuid.UUID(test_user["user_data"]["id"])
+    account_id = uuid.UUID(test_user["user_data"]["account_id"])
+
+    invite = AccountInvite(
+        account_id=account_id,
+        invited_by_id=invited_by_id,
+        email="used@example.com",
+        code="USEDCODE01",
+        role="engineer",
+        accepted_by_id=invited_by_id,  # mark as used
+        expires_at=datetime.now(timezone.utc) + timedelta(days=7),
+    )
+    test_db.add(invite)
+    await test_db.commit()
+    invite_id = invite.id
+
+    response = await client.delete(
+        f"/api/v1/accounts/me/invites/{invite_id}",
+        headers=auth_headers,
+    )
+    assert response.status_code == 400

backend/tests/test_account_invite_model.py

@@ -0,0 +1,27 @@
+import pytest
+from datetime import datetime, timezone, timedelta
+from app.models.account_invite import AccountInvite
+
+
+def make_invite(**kwargs):
+    return AccountInvite(
+        account_id=kwargs.get("account_id", "00000000-0000-0000-0000-000000000001"),
+        invited_by_id=kwargs.get("invited_by_id", "00000000-0000-0000-0000-000000000002"),
+        email=kwargs.get("email", "x@y.com"),
+        code=kwargs.get("code", "ABCD1234"),
+        role=kwargs.get("role", "engineer"),
+        accepted_by_id=kwargs.get("accepted_by_id"),
+        expires_at=kwargs.get("expires_at"),
+        revoked_at=kwargs.get("revoked_at"),
+    )
+
+
+def test_invite_revoked_is_invalid():
+    invite = make_invite(revoked_at=datetime.now(timezone.utc))
+    assert invite.is_revoked is True
+    assert invite.is_valid is False
+
+
+def test_invite_unrevoked_unexpired_unused_is_valid():
+    invite = make_invite(expires_at=datetime.now(timezone.utc) + timedelta(days=7))
+    assert invite.is_valid is True

backend/tests/test_account_management.py

@@ -21,17 +21,21 @@ class TestAccountEndpoints:
 
     @pytest.mark.asyncio
     async def test_get_my_subscription(self, client: AsyncClient, auth_headers: dict):
-        """Test getting current user's subscription details."""
+        """Test getting current user's subscription details.
+
+        The test_user fixture seeds a Pro/active Subscription so
+        Pro-guarded routers work; reflect that in the expected plan.
+        """
         response = await client.get("/api/v1/accounts/me/subscription", headers=auth_headers)
         assert response.status_code == 200
         data = response.json()
         assert "subscription" in data
         assert "limits" in data
         assert "usage" in data
-        assert data["subscription"]["plan"] == "free"
+        assert data["subscription"]["plan"] == "pro"
         assert data["subscription"]["status"] == "active"
-        assert data["limits"]["max_trees"] == 3
-        assert data["limits"]["max_sessions_per_month"] == 20
+        assert data["limits"]["max_trees"] == 25
+        assert data["limits"]["max_sessions_per_month"] == 200
 
     @pytest.mark.asyncio
     async def test_get_my_members(self, client: AsyncClient, auth_headers: dict):

backend/tests/test_billing_checkout.py

@@ -0,0 +1,56 @@
+import pytest
+from unittest.mock import patch, MagicMock
+from app.models.plan_billing import PlanBilling
+
+
+@pytest.mark.asyncio
+async def test_checkout_session_creates_stripe_session(
+    client, test_db, test_user, auth_headers, monkeypatch
+):
+    """End-to-end: post body → Stripe SDK called → URL returned. Stripe SDK
+    mocked; Customer + Session calls patched."""
+    from app.core.config import settings
+    monkeypatch.setattr(settings, "STRIPE_SECRET_KEY", "sk_test_dummy")
+
+    test_db.add(PlanBilling(
+        plan="pro",
+        display_name="Pro",
+        stripe_product_id="prod_test",
+        stripe_monthly_price_id="price_test_monthly",
+    ))
+    await test_db.commit()
+
+    fake_customer = MagicMock()
+    fake_customer.id = "cus_test_123"
+    fake_session = MagicMock()
+    fake_session.url = "https://checkout.stripe.com/test"
+
+    with patch("stripe.Customer.create", return_value=fake_customer) as cust_mock, \
+         patch("stripe.checkout.Session.create", return_value=fake_session) as sess_mock:
+        response = await client.post(
+            "/api/v1/billing/checkout-session",
+            json={"plan": "pro", "seats": 3, "billing_interval": "monthly"},
+            headers=auth_headers,
+        )
+
+    assert response.status_code == 200, response.json()
+    assert response.json()["url"] == "https://checkout.stripe.com/test"
+    cust_mock.assert_called_once()
+    sess_mock.assert_called_once()
+
+
+@pytest.mark.asyncio
+async def test_checkout_session_unknown_plan_returns_500(
+    client, test_db, test_user, auth_headers, monkeypatch
+):
+    """No PlanBilling row → ValueError surfaces as 500 (the endpoint doesn't
+    catch business errors)."""
+    from app.core.config import settings
+    monkeypatch.setattr(settings, "STRIPE_SECRET_KEY", "sk_test_dummy")
+
+    response = await client.post(
+        "/api/v1/billing/checkout-session",
+        json={"plan": "pro", "seats": 1, "billing_interval": "monthly"},
+        headers=auth_headers,
+    )
+    assert response.status_code == 500

backend/tests/test_billing_service.py

@@ -0,0 +1,80 @@
+import uuid
+import pytest
+from datetime import datetime, timezone
+from sqlalchemy import select, delete
+from app.models.subscription import Subscription
+from app.services.billing import BillingService
+
+
+@pytest.mark.asyncio
+async def test_start_trial_creates_trialing_pro_subscription(test_db):
+    """Direct service test — bypasses register, creates account inline."""
+    from app.models.account import Account
+    account = Account(name="DirectTest", display_code="DIRECT01")
+    test_db.add(account)
+    await test_db.flush()
+
+    sub = await BillingService.start_trial(test_db, account.id)
+    assert sub.plan == "pro"
+    assert sub.status == "trialing"
+    assert sub.current_period_end is not None
+    assert sub.current_period_end > datetime.now(timezone.utc)
+
+
+@pytest.mark.asyncio
+async def test_start_trial_is_idempotent(test_db):
+    from app.models.account import Account
+    account = Account(name="Idempo", display_code="IDEMPO01")
+    test_db.add(account)
+    await test_db.flush()
+
+    sub1 = await BillingService.start_trial(test_db, account.id)
+    sub2 = await BillingService.start_trial(test_db, account.id)
+    assert sub1.id == sub2.id
+
+    rows = (await test_db.execute(
+        select(Subscription).where(Subscription.account_id == account.id)
+    )).scalars().all()
+    assert len(rows) == 1
+
+
+@pytest.mark.asyncio
+async def test_register_creates_trial_subscription(client, test_db):
+    """Registering a brand-new shop (no invite code) yields a Pro/trialing sub."""
+    response = await client.post("/api/v1/auth/register", json={
+        "email": "newshop@example.com",
+        "password": "Verystrong1Pwd",
+        "name": "New Shop",
+    })
+    assert response.status_code in (200, 201), response.json()
+
+    body = response.json()
+    account_id = uuid.UUID(body["account_id"])
+
+    sub = (await test_db.execute(
+        select(Subscription).where(Subscription.account_id == account_id)
+    )).scalar_one()
+    assert sub.plan == "pro"
+    assert sub.status == "trialing"
+    assert sub.current_period_end is not None
+
+
+@pytest.mark.asyncio
+async def test_apply_subscription_event_is_idempotent(test_db):
+    payload = {
+        "data": {"object": {
+            "id": "evt_test_1",
+            "customer": "cus_xxx",
+            "subscription": "sub_xxx",
+            "status": "active",
+        }}
+    }
+
+    applied_first = await BillingService.apply_subscription_event(
+        test_db, "evt_test_1", "customer.subscription.updated", payload
+    )
+    applied_second = await BillingService.apply_subscription_event(
+        test_db, "evt_test_1", "customer.subscription.updated", payload
+    )
+    assert applied_first is True
+    assert applied_second is False  # already-processed → ack without re-applying

backend/tests/test_billing_state_endpoint.py

@@ -0,0 +1,64 @@
+import uuid
+import pytest
+from sqlalchemy import select
+from app.models.subscription import Subscription
+from app.models.feature_flag import FeatureFlag, PlanFeatureDefault, AccountFeatureOverride
+
+
+@pytest.mark.asyncio
+async def test_billing_state_returns_subscription_plan_features(
+    client, test_db, test_user, auth_headers
+):
+    """Subscription is already seeded by test_user fixture (pro/active).
+    Add a feature flag default for `pro` and verify it shows up in the response."""
+    flag = FeatureFlag(flag_key="psa_integration", display_name="PSA Integration")
+    test_db.add(flag)
+    await test_db.flush()
+    test_db.add(PlanFeatureDefault(plan="pro", flag_id=flag.id, enabled=True))
+    await test_db.commit()
+
+    response = await client.get("/api/v1/billing/state", headers=auth_headers)
+    assert response.status_code == 200, response.json()
+    body = response.json()
+    assert body["subscription"]["status"] == "active"
+    assert body["subscription"]["plan"] == "pro"
+    assert body["subscription"]["has_pro_entitlement"] is True
+    assert body["subscription"]["is_paid"] is True
+    assert body["enabled_features"]["psa_integration"] is True
+    # plan_limits should be a dict with the seeded pro limits from conftest
+    assert body["plan_limits"]["plan"] == "pro"
+    assert body["plan_limits"]["max_trees"] == 25
+
+
+@pytest.mark.asyncio
+async def test_billing_state_account_override_beats_plan_default(
+    client, test_db, test_user, auth_headers
+):
+    account_id = uuid.UUID(test_user["user_data"]["account_id"])
+
+    flag = FeatureFlag(flag_key="escalation_mode", display_name="Escalation Mode")
+    test_db.add(flag)
+    await test_db.flush()
+    test_db.add(PlanFeatureDefault(plan="pro", flag_id=flag.id, enabled=False))
+    test_db.add(AccountFeatureOverride(
+        account_id=account_id, flag_id=flag.id, enabled=True,
+    ))
+    await test_db.commit()
+
+    response = await client.get("/api/v1/billing/state", headers=auth_headers)
+    assert response.status_code == 200
+    assert response.json()["enabled_features"]["escalation_mode"] is True
+
+
+@pytest.mark.asyncio
+async def test_billing_state_404_when_no_subscription(
+    client, test_db, test_user, auth_headers
+):
+    """Wipe the seeded subscription and verify the endpoint surfaces 404."""
+    from sqlalchemy import delete
+    account_id = uuid.UUID(test_user["user_data"]["account_id"])
+    await test_db.execute(delete(Subscription).where(Subscription.account_id == account_id))
+    await test_db.commit()
+
+    response = await client.get("/api/v1/billing/state", headers=auth_headers)
+    assert response.status_code == 404

backend/tests/test_email_verification_autosend.py

@@ -0,0 +1,98 @@
+import pytest
+from datetime import datetime, timezone, timedelta
+from unittest.mock import AsyncMock, patch
+from sqlalchemy import select
+
+
+@pytest.mark.asyncio
+async def test_register_auto_sends_verification_email(client, test_db):
+    """Fresh registration triggers send_email_verification_email."""
+    with patch(
+        "app.core.email.EmailService.send_email_verification_email",
+        new_callable=AsyncMock,
+    ) as mock_send:
+        response = await client.post("/api/v1/auth/register", json={
+            "email": "newshop@example.com",
+            "password": "Verystrong1Pwd",
+            "name": "New Shop",
+        })
+        assert response.status_code in (200, 201), response.json()
+        mock_send.assert_called_once()
+        kwargs = mock_send.call_args.kwargs
+        assert kwargs["to_email"] == "newshop@example.com"
+        assert "/verify-email?token=" in kwargs["verification_url"]
+
+
+@pytest.mark.asyncio
+async def test_register_with_account_invite_code_email_mismatch_rejected(
+    client, test_db, test_user
+):
+    """Invite code is for invited@example.com but user registers with a
+    different email -> 400 invite_email_mismatch."""
+    from app.models.account_invite import AccountInvite
+    import uuid
+
+    invited_by_id = uuid.UUID(test_user["user_data"]["id"])
+    account_id = uuid.UUID(test_user["user_data"]["account_id"])
+
+    invite = AccountInvite(
+        account_id=account_id,
+        invited_by_id=invited_by_id,
+        email="invited@example.com",
+        code="INVITECODE99",
+        role="engineer",
+        expires_at=datetime.now(timezone.utc) + timedelta(days=7),
+    )
+    test_db.add(invite)
+    await test_db.commit()
+
+    response = await client.post("/api/v1/auth/register", json={
+        "email": "wrong-email@example.com",
+        "password": "Verystrong1Pwd",
+        "name": "Wrong Email",
+        "account_invite_code": "INVITECODE99",
+    })
+    assert response.status_code == 400, response.json()
+    assert response.json()["detail"]["error"] == "invite_email_mismatch"
+
+
+@pytest.mark.asyncio
+async def test_register_with_account_invite_code_email_match_accepted(
+    client, test_db, test_user
+):
+    """Invite code is for invited@example.com - registering with that email
+    succeeds and joins the existing account."""
+    from app.models.account_invite import AccountInvite
+    from app.models.user import User
+    import uuid
+
+    invited_by_id = uuid.UUID(test_user["user_data"]["id"])
+    account_id = uuid.UUID(test_user["user_data"]["account_id"])
+
+    invite = AccountInvite(
+        account_id=account_id,
+        invited_by_id=invited_by_id,
+        email="invited@example.com",
+        code="INVITECODE100",
+        role="engineer",
+        expires_at=datetime.now(timezone.utc) + timedelta(days=7),
+    )
+    test_db.add(invite)
+    await test_db.commit()
+
+    with patch(
+        "app.core.email.EmailService.send_email_verification_email",
+        new_callable=AsyncMock,
+    ):
+        response = await client.post("/api/v1/auth/register", json={
+            "email": "invited@example.com",
+            "password": "Verystrong1Pwd",
+            "name": "Invited",
+            "account_invite_code": "INVITECODE100",
+        })
+    assert response.status_code in (200, 201), response.json()
+
+    new_user = (await test_db.execute(
+        select(User).where(User.email == "invited@example.com")
+    )).scalar_one()
+    assert new_user.account_id == account_id  # joined existing account

backend/tests/test_email_verification_guard.py

@@ -0,0 +1,87 @@
+import uuid
+import pytest
+from datetime import datetime, timezone, timedelta
+from sqlalchemy import select
+from app.models.user import User
+
+
+async def _set_user_email_state(test_db, user_id, *, verified_at=None, created_at=None):
+    user = (await test_db.execute(select(User).where(User.id == user_id))).scalar_one()
+    user.email_verified_at = verified_at
+    if created_at is not None:
+        user.created_at = created_at
+    await test_db.commit()
+
+
+@pytest.mark.asyncio
+async def test_verified_user_passes(client, test_db, test_user, auth_headers):
+    user_id = uuid.UUID(test_user["user_data"]["id"])
+    await _set_user_email_state(test_db, user_id, verified_at=datetime.now(timezone.utc))
+    response = await client.get("/api/v1/trees", headers=auth_headers)
+    assert response.status_code != 403
+
+
+@pytest.mark.asyncio
+async def test_unverified_in_grace_passes(client, test_db, test_user, auth_headers):
+    user_id = uuid.UUID(test_user["user_data"]["id"])
+    await _set_user_email_state(
+        test_db, user_id,
+        verified_at=None,
+        created_at=datetime.now(timezone.utc) - timedelta(days=2),
+    )
+    response = await client.get("/api/v1/trees", headers=auth_headers)
+    assert response.status_code != 403
+
+
+@pytest.mark.asyncio
+async def test_unverified_past_grace_blocks(client, test_db, test_user, auth_headers):
+    user_id = uuid.UUID(test_user["user_data"]["id"])
+    await _set_user_email_state(
+        test_db, user_id,
+        verified_at=None,
+        created_at=datetime.now(timezone.utc) - timedelta(days=10),
+    )
+    response = await client.get("/api/v1/trees", headers=auth_headers)
+    assert response.status_code == 403
+    body = response.json()
+    assert body["detail"]["error"] == "email_not_verified"
+
+
+@pytest.mark.asyncio
+async def test_unverified_past_grace_allowlisted_still_passes(client, test_db, test_user, auth_headers):
+    user_id = uuid.UUID(test_user["user_data"]["id"])
+    await _set_user_email_state(
+        test_db, user_id,
+        verified_at=None,
+        created_at=datetime.now(timezone.utc) - timedelta(days=10),
+    )
+    response = await client.get("/api/v1/auth/me", headers=auth_headers)
+    assert response.status_code == 200
+
+
+@pytest.mark.asyncio
+async def test_combined_guards_unverified_expired_trial(client, test_db, test_user, auth_headers):
+    """A user who is BOTH past grace AND on an expired trial should get blocked
+    by one of the two guards. Either error is acceptable; we just verify a
+    refusal."""
+    from app.models.subscription import Subscription
+    from sqlalchemy import delete
+
+    user_id = uuid.UUID(test_user["user_data"]["id"])
+    account_id = uuid.UUID(test_user["user_data"]["account_id"])
+    await _set_user_email_state(
+        test_db, user_id,
+        verified_at=None,
+        created_at=datetime.now(timezone.utc) - timedelta(days=10),
+    )
+
+    # Replace the seeded active sub with an expired trial
+    await test_db.execute(delete(Subscription).where(Subscription.account_id == account_id))
+    test_db.add(Subscription(
+        account_id=account_id, plan="pro", status="trialing",
+        current_period_end=datetime.now(timezone.utc) - timedelta(hours=1),
+    ))
+    await test_db.commit()
+
+    response = await client.get("/api/v1/trees", headers=auth_headers)
+    assert response.status_code in (402, 403)

backend/tests/test_escalation_bus.py

@@ -0,0 +1,121 @@
+"""Unit tests for the in-memory escalation pub/sub bus."""
+import asyncio
+from uuid import uuid4
+
+import pytest
+
+from app.core.escalation_bus import EscalationBus
+
+
+@pytest.mark.asyncio
+async def test_publish_with_no_subscribers_returns_zero():
+    bus = EscalationBus()
+    delivered = await bus.publish(uuid4(), {"type": "handoff_created"})
+    assert delivered == 0
+
+
+@pytest.mark.asyncio
+async def test_subscribe_then_publish_delivers_event():
+    bus = EscalationBus()
+    account = uuid4()
+    queue = await bus.subscribe(account)
+    try:
+        delivered = await bus.publish(account, {"type": "handoff_created", "id": "x"})
+        assert delivered == 1
+        event = await asyncio.wait_for(queue.get(), timeout=1.0)
+        assert event == {"type": "handoff_created", "id": "x"}
+    finally:
+        await bus.unsubscribe(account, queue)
+
+
+@pytest.mark.asyncio
+async def test_two_subscribers_same_account_both_receive():
+    bus = EscalationBus()
+    account = uuid4()
+    q1 = await bus.subscribe(account)
+    q2 = await bus.subscribe(account)
+    try:
+        delivered = await bus.publish(account, {"type": "x"})
+        assert delivered == 2
+        e1 = await asyncio.wait_for(q1.get(), timeout=1.0)
+        e2 = await asyncio.wait_for(q2.get(), timeout=1.0)
+        assert e1 == e2 == {"type": "x"}
+    finally:
+        await bus.unsubscribe(account, q1)
+        await bus.unsubscribe(account, q2)
+
+
+@pytest.mark.asyncio
+async def test_subscriber_in_other_account_does_not_receive():
+    """Cross-tenant isolation is the whole point — sanity check it directly."""
+    bus = EscalationBus()
+    account_a = uuid4()
+    account_b = uuid4()
+    q_a = await bus.subscribe(account_a)
+    q_b = await bus.subscribe(account_b)
+    try:
+        delivered = await bus.publish(account_a, {"type": "x"})
+        assert delivered == 1
+
+        e_a = await asyncio.wait_for(q_a.get(), timeout=1.0)
+        assert e_a == {"type": "x"}
+
+        # B's queue must remain empty.
+        with pytest.raises(asyncio.TimeoutError):
+            await asyncio.wait_for(q_b.get(), timeout=0.1)
+    finally:
+        await bus.unsubscribe(account_a, q_a)
+        await bus.unsubscribe(account_b, q_b)
+
+
+@pytest.mark.asyncio
+async def test_publish_normalizes_string_uuid_account_id():
+    """ORM-created objects can briefly carry string UUIDs in-memory."""
+    bus = EscalationBus()
+    account = uuid4()
+    queue = await bus.subscribe(account)
+    try:
+        delivered = await bus.publish(str(account), {"type": "x"})
+        assert delivered == 1
+        event = await asyncio.wait_for(queue.get(), timeout=1.0)
+        assert event == {"type": "x"}
+    finally:
+        await bus.unsubscribe(str(account), queue)
+
+
+@pytest.mark.asyncio
+async def test_unsubscribe_drops_subscriber_count_to_zero():
+    bus = EscalationBus()
+    account = uuid4()
+    q = await bus.subscribe(account)
+    assert bus.subscriber_count(account) == 1
+    await bus.unsubscribe(account, q)
+    assert bus.subscriber_count(account) == 0
+
+
+@pytest.mark.asyncio
+async def test_publish_drops_events_when_subscriber_queue_is_full():
+    """A stuck subscriber must not back-pressure publishers."""
+    bus = EscalationBus()
+    account = uuid4()
+    queue = await bus.subscribe(account)
+    try:
+        # Stuff the queue past capacity (maxsize is 64) without consuming.
+        for _ in range(65):
+            await bus.publish(account, {"type": "x"})
+        # Sanity: queue holds at most maxsize.
+        assert queue.qsize() <= 64
+        # Publishes after capacity didn't raise — they were dropped silently.
+    finally:
+        await bus.unsubscribe(account, queue)
+
+
+@pytest.mark.asyncio
+async def test_unsubscribe_unknown_queue_is_noop():
+    """Defensive: unsubscribe on an account/queue that isn't registered
+    should not raise — finally blocks rely on this."""
+    bus = EscalationBus()
+    account = uuid4()
+    fake_queue: asyncio.Queue = asyncio.Queue()
+    # Should not raise.
+    await bus.unsubscribe(account, fake_queue)

backend/tests/test_fix_outcome_endpoint.py

@@ -193,6 +193,95 @@ async def test_applied_at_auto_stamped_on_first_outcome(
     assert body["verified_at"] is not None
 
 
+@pytest.mark.asyncio
+async def test_pending_requires_notes(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    """applied_pending requires notes (the "what are you waiting on?" reason)."""
+    session_id, fix_id = await _make_session_with_fix(test_db, test_user)
+
+    r = await client.patch(
+        f"/api/v1/ai-sessions/{session_id}/suggested-fixes/{fix_id}/outcome",
+        headers=auth_headers,
+        json={"outcome": "applied_pending"},
+    )
+    assert r.status_code == 400
+    assert "notes" in r.text.lower()
+
+
+@pytest.mark.asyncio
+async def test_pending_stores_reason_and_stamps_applied_at(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    """applied_pending stores notes under pending_reason and stamps applied_at
+    but NOT verified_at — the fix is parked, not verified."""
+    session_id, fix_id = await _make_session_with_fix(test_db, test_user)
+    r = await client.patch(
+        f"/api/v1/ai-sessions/{session_id}/suggested-fixes/{fix_id}/outcome",
+        headers=auth_headers,
+        json={"outcome": "applied_pending", "notes": "client power-cycling router"},
+    )
+    assert r.status_code == 200, r.text
+    body = r.json()
+    assert body["status"] == "applied_pending"
+    assert body["pending_reason"] == "client power-cycling router"
+    assert body["applied_at"] is not None
+    assert body["verified_at"] is None
+    assert body["partial_notes"] is None
+    assert body["failure_reason"] is None
+
+
+@pytest.mark.asyncio
+async def test_pending_to_success_allowed(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    """pending is non-terminal — engineer can advance to success once verified."""
+    session_id, fix_id = await _make_session_with_fix(test_db, test_user)
+
+    r1 = await client.patch(
+        f"/api/v1/ai-sessions/{session_id}/suggested-fixes/{fix_id}/outcome",
+        headers=auth_headers,
+        json={"outcome": "applied_pending", "notes": "waiting on AD replication"},
+    )
+    assert r1.status_code == 200
+
+    r2 = await client.patch(
+        f"/api/v1/ai-sessions/{session_id}/suggested-fixes/{fix_id}/outcome",
+        headers=auth_headers,
+        json={"outcome": "applied_success"},
+    )
+    assert r2.status_code == 200
+    body = r2.json()
+    assert body["status"] == "applied_success"
+    assert body["verified_at"] is not None
+    # pending_reason is preserved as audit trail
+    assert body["pending_reason"] == "waiting on AD replication"
+
+
+@pytest.mark.asyncio
+async def test_pending_reason_can_be_updated(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    """pending→pending with new notes updates the stored pending_reason."""
+    session_id, fix_id = await _make_session_with_fix(test_db, test_user)
+
+    r1 = await client.patch(
+        f"/api/v1/ai-sessions/{session_id}/suggested-fixes/{fix_id}/outcome",
+        json={"outcome": "applied_pending", "notes": "waiting on AD replication"},
+        headers=auth_headers,
+    )
+    assert r1.status_code == 200
+    assert r1.json()["pending_reason"] == "waiting on AD replication"
+
+    r2 = await client.patch(
+        f"/api/v1/ai-sessions/{session_id}/suggested-fixes/{fix_id}/outcome",
+        json={"outcome": "applied_pending", "notes": "now waiting on client to confirm login"},
+        headers=auth_headers,
+    )
+    assert r2.status_code == 200
+    assert r2.json()["pending_reason"] == "now waiting on client to confirm login"
+
+
 @pytest.mark.asyncio
 async def test_failed_outcome_stores_notes_as_failure_reason(
     client: AsyncClient, test_user, auth_headers, test_db

backend/tests/test_flowpilot_analytics_escalations.py

@@ -0,0 +1,363 @@
+"""Tests for GET /analytics/flowpilot/escalations — Escalation Mode wedge metric.
+
+Covers the in-product time-to-first-action measurement that powers the queue
+stat-card and the analytics page. The savings claim itself comes from the
+manual baseline (the Assignment); these tests only cover what the in-product
+endpoint returns.
+"""
+from datetime import datetime, timedelta, timezone
+from uuid import UUID as PyUUID
+
+import pytest
+from httpx import AsyncClient
+from sqlalchemy import select
+
+from app.models.ai_session import AISession
+from app.models.ai_session_step import AISessionStep
+from app.models.session_handoff import SessionHandoff
+from app.models.user import User
+
+
+URL = "/api/v1/analytics/flowpilot/escalations"
+
+
+# ─── Helpers ──────────────────────────────────────────────────────────────────
+
+
+async def _make_session(db, *, user_id, account_id) -> AISession:
+    s = AISession(
+        user_id=user_id,
+        account_id=account_id,
+        session_type="guided",
+        intake_type="free_text",
+        intake_content={"text": "test"},
+        status="escalated",
+        confidence_tier="discovery",
+        conversation_messages=[],
+    )
+    db.add(s)
+    await db.flush()
+    return s
+
+
+async def _make_handoff(
+    db,
+    *,
+    session_id,
+    account_id,
+    user_id,
+    claimed_at: datetime | None,
+    claimed_by=None,
+) -> SessionHandoff:
+    h = SessionHandoff(
+        session_id=session_id,
+        account_id=account_id,
+        handed_off_by=user_id,
+        intent="escalate",
+        snapshot={"branch_map": "stub"},
+        priority="normal",
+        claimed_at=claimed_at,
+        claimed_by=claimed_by,
+    )
+    db.add(h)
+    await db.flush()
+    return h
+
+
+async def _make_step(db, *, session_id, account_id, created_at: datetime) -> AISessionStep:
+    """Insert an ai_session_step row with an explicit created_at.
+
+    SQLAlchemy's default would set created_at to now(); the metric query keys
+    off this column so the tests need to control it directly.
+    """
+    step = AISessionStep(
+        session_id=session_id,
+        account_id=account_id,
+        step_order=1,
+        step_type="note",
+        content={"text": "first action"},
+        confidence_at_step=0.5,
+        input_tokens=0,
+        output_tokens=0,
+        is_fork_point=False,
+        was_free_text=False,
+        was_skipped=False,
+        created_at=created_at,
+    )
+    db.add(step)
+    await db.flush()
+    return step
+
+
+# ─── Tests ────────────────────────────────────────────────────────────────────
+
+
+@pytest.mark.asyncio
+async def test_returns_zero_metrics_when_no_handoffs(
+    client: AsyncClient, auth_headers, test_user
+):
+    """Empty account → n_handoffs_claimed=0, all stats None, 200 OK."""
+    response = await client.get(URL, headers=auth_headers)
+    assert response.status_code == 200
+    body = response.json()
+    assert body["period"] == "30d"
+    assert body["n_handoffs_claimed"] == 0
+    assert body["n_handoffs_with_action"] == 0
+    assert body["avg_seconds_to_first_action"] is None
+    assert body["median_seconds_to_first_action"] is None
+    assert body["p95_seconds_to_first_action"] is None
+    # Disclaimer is part of the contract — pilots reading the API should see it.
+    assert "manual baseline" in body["metric_definition"].lower()
+
+
+@pytest.mark.asyncio
+async def test_happy_path_single_handoff_with_action(
+    client: AsyncClient, auth_headers, test_user, test_db
+):
+    """One claimed handoff + a step 90s later → avg=median=p95=90.0."""
+    user_id = PyUUID(test_user["user_data"]["id"])
+    account_id = PyUUID(test_user["user_data"]["account_id"])
+
+    claimed_at = datetime.now(timezone.utc) - timedelta(hours=2)
+    first_action_at = claimed_at + timedelta(seconds=90)
+
+    session = await _make_session(test_db, user_id=user_id, account_id=account_id)
+    await _make_handoff(
+        test_db,
+        session_id=session.id,
+        account_id=account_id,
+        user_id=user_id,
+        claimed_at=claimed_at,
+        claimed_by=user_id,
+    )
+    await _make_step(
+        test_db,
+        session_id=session.id,
+        account_id=account_id,
+        created_at=first_action_at,
+    )
+    await test_db.commit()
+
+    response = await client.get(URL, headers=auth_headers)
+    assert response.status_code == 200
+    body = response.json()
+    assert body["n_handoffs_claimed"] == 1
+    assert body["n_handoffs_with_action"] == 1
+    assert body["avg_seconds_to_first_action"] == 90.0
+    assert body["median_seconds_to_first_action"] == 90.0
+    assert body["p95_seconds_to_first_action"] == 90.0
+
+
+@pytest.mark.asyncio
+async def test_handoff_claimed_but_no_action(
+    client: AsyncClient, auth_headers, test_user, test_db
+):
+    """Claimed handoff with no post-claim step → counted in n_handoffs_claimed
+    but not in n_handoffs_with_action; aggregates remain None."""
+    user_id = PyUUID(test_user["user_data"]["id"])
+    account_id = PyUUID(test_user["user_data"]["account_id"])
+    claimed_at = datetime.now(timezone.utc) - timedelta(minutes=5)
+
+    session = await _make_session(test_db, user_id=user_id, account_id=account_id)
+    await _make_handoff(
+        test_db,
+        session_id=session.id,
+        account_id=account_id,
+        user_id=user_id,
+        claimed_at=claimed_at,
+        claimed_by=user_id,
+    )
+    # Pre-claim step (created_at < claimed_at) — must NOT count.
+    await _make_step(
+        test_db,
+        session_id=session.id,
+        account_id=account_id,
+        created_at=claimed_at - timedelta(seconds=30),
+    )
+    await test_db.commit()
+
+    response = await client.get(URL, headers=auth_headers)
+    assert response.status_code == 200
+    body = response.json()
+    assert body["n_handoffs_claimed"] == 1
+    assert body["n_handoffs_with_action"] == 0
+    assert body["avg_seconds_to_first_action"] is None
+
+
+@pytest.mark.asyncio
+async def test_unclaimed_handoffs_excluded(
+    client: AsyncClient, auth_headers, test_user, test_db
+):
+    """Handoffs with claimed_at IS NULL are excluded entirely."""
+    user_id = PyUUID(test_user["user_data"]["id"])
+    account_id = PyUUID(test_user["user_data"]["account_id"])
+
+    session = await _make_session(test_db, user_id=user_id, account_id=account_id)
+    await _make_handoff(
+        test_db,
+        session_id=session.id,
+        account_id=account_id,
+        user_id=user_id,
+        claimed_at=None,
+    )
+    await test_db.commit()
+
+    response = await client.get(URL, headers=auth_headers)
+    assert response.status_code == 200
+    assert response.json()["n_handoffs_claimed"] == 0
+
+
+@pytest.mark.asyncio
+async def test_period_window_excludes_old_handoffs(
+    client: AsyncClient, auth_headers, test_user, test_db
+):
+    """A handoff claimed >7d ago must not appear in ?period=7d."""
+    user_id = PyUUID(test_user["user_data"]["id"])
+    account_id = PyUUID(test_user["user_data"]["account_id"])
+
+    old_claimed_at = datetime.now(timezone.utc) - timedelta(days=10)
+    session = await _make_session(test_db, user_id=user_id, account_id=account_id)
+    await _make_handoff(
+        test_db,
+        session_id=session.id,
+        account_id=account_id,
+        user_id=user_id,
+        claimed_at=old_claimed_at,
+        claimed_by=user_id,
+    )
+    await _make_step(
+        test_db,
+        session_id=session.id,
+        account_id=account_id,
+        created_at=old_claimed_at + timedelta(seconds=60),
+    )
+    await test_db.commit()
+
+    # 7d window: excluded
+    r7 = await client.get(URL, headers=auth_headers, params={"period": "7d"})
+    assert r7.status_code == 200
+    assert r7.json()["n_handoffs_claimed"] == 0
+
+    # 90d window: included
+    r90 = await client.get(URL, headers=auth_headers, params={"period": "90d"})
+    assert r90.status_code == 200
+    assert r90.json()["n_handoffs_claimed"] == 1
+    assert r90.json()["n_handoffs_with_action"] == 1
+
+
+@pytest.mark.asyncio
+async def test_aggregate_stats_for_multiple_handoffs(
+    client: AsyncClient, auth_headers, test_user, test_db
+):
+    """Three handoffs with deltas 30/60/180s → avg=90, median=60, p95≈180."""
+    user_id = PyUUID(test_user["user_data"]["id"])
+    account_id = PyUUID(test_user["user_data"]["account_id"])
+
+    base = datetime.now(timezone.utc) - timedelta(hours=3)
+    deltas = [30, 60, 180]
+    for i, delta in enumerate(deltas):
+        s = await _make_session(test_db, user_id=user_id, account_id=account_id)
+        claimed_at = base + timedelta(minutes=i * 10)
+        await _make_handoff(
+            test_db,
+            session_id=s.id,
+            account_id=account_id,
+            user_id=user_id,
+            claimed_at=claimed_at,
+            claimed_by=user_id,
+        )
+        await _make_step(
+            test_db,
+            session_id=s.id,
+            account_id=account_id,
+            created_at=claimed_at + timedelta(seconds=delta),
+        )
+    await test_db.commit()
+
+    response = await client.get(URL, headers=auth_headers)
+    body = response.json()
+    assert response.status_code == 200
+    assert body["n_handoffs_claimed"] == 3
+    assert body["n_handoffs_with_action"] == 3
+    assert body["avg_seconds_to_first_action"] == 90.0
+    assert body["median_seconds_to_first_action"] == 60.0
+    assert body["p95_seconds_to_first_action"] == 180.0
+
+
+@pytest.mark.asyncio
+async def test_account_isolation_requesting_user_only_sees_own_account(
+    client: AsyncClient, auth_headers, test_user, test_db
+):
+    """A handoff in another account must not appear in this user's response.
+
+    Critical: the Phase 4 RLS pattern can fail silently if account_id is wrong.
+    This test would catch an account-scoped query that accidentally returned
+    cross-tenant rows.
+    """
+    from app.models.account import Account
+
+    other_account = Account(name="Other MSP", display_code="OTHER001")
+    test_db.add(other_account)
+    await test_db.flush()
+
+    other_user = User(
+        email="other@example.com",
+        password_hash="x",
+        name="Other Tech",
+        role="engineer",
+        account_id=other_account.id,
+        account_role="owner",
+    )
+    test_db.add(other_user)
+    await test_db.flush()
+
+    s = await _make_session(
+        test_db, user_id=other_user.id, account_id=other_account.id
+    )
+    claimed_at = datetime.now(timezone.utc) - timedelta(hours=1)
+    await _make_handoff(
+        test_db,
+        session_id=s.id,
+        account_id=other_account.id,
+        user_id=other_user.id,
+        claimed_at=claimed_at,
+        claimed_by=other_user.id,
+    )
+    await _make_step(
+        test_db,
+        session_id=s.id,
+        account_id=other_account.id,
+        created_at=claimed_at + timedelta(seconds=45),
+    )
+    await test_db.commit()
+
+    response = await client.get(URL, headers=auth_headers)
+    assert response.status_code == 200
+    body = response.json()
+    # The other account's handoff must NOT leak into this account's response.
+    assert body["n_handoffs_claimed"] == 0
+    assert body["n_handoffs_with_action"] == 0
+
+
+@pytest.mark.asyncio
+async def test_viewer_role_is_blocked(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    """Downgrade the test user to 'viewer' and confirm the endpoint 403s."""
+    user_id = PyUUID(test_user["user_data"]["id"])
+    user = (
+        await test_db.execute(select(User).where(User.id == user_id))
+    ).scalar_one()
+    user.account_role = "viewer"
+    await test_db.commit()
+
+    response = await client.get(URL, headers=auth_headers)
+    assert response.status_code == 403
+    assert "engineer" in response.json()["detail"].lower()
+
+
+@pytest.mark.asyncio
+async def test_invalid_period_rejected(client: AsyncClient, auth_headers):
+    """period=1d is not in {7d,30d,90d} — must 422."""
+    response = await client.get(URL, headers=auth_headers, params={"period": "1d"})
+    assert response.status_code == 422

backend/tests/test_get_current_active_user_no_mutation.py

@@ -0,0 +1,45 @@
+import uuid
+import pytest
+from datetime import datetime, timezone, timedelta
+from sqlalchemy import select
+from app.models.subscription import Subscription
+
+
+@pytest.mark.asyncio
+async def test_expired_trial_is_not_mutated_by_get_current_active_user(
+    test_db, client, test_user, auth_headers
+):
+    """The previous deps.py:109 logic mutated trialing→active+free on expiry.
+    That's gone. An expired-trial Subscription should retain status='trialing'
+    and current_period_end after any authenticated request."""
+    account_id = uuid.UUID(test_user["user_data"]["account_id"])
+
+    # If a Subscription already exists for this account (e.g. created by
+    # the register handler), update it; otherwise insert a new one.
+    existing = await test_db.execute(
+        select(Subscription).where(Subscription.account_id == account_id)
+    )
+    sub = existing.scalar_one_or_none()
+    expired_end = datetime.now(timezone.utc) - timedelta(hours=1)
+    if sub is None:
+        sub = Subscription(
+            account_id=account_id,
+            plan="pro",
+            status="trialing",
+            current_period_end=expired_end,
+        )
+        test_db.add(sub)
+    else:
+        sub.plan = "pro"
+        sub.status = "trialing"
+        sub.current_period_end = expired_end
+    await test_db.commit()
+
+    # Call any authenticated endpoint that goes through get_current_active_user.
+    response = await client.get("/api/v1/auth/me", headers=auth_headers)
+    assert response.status_code == 200
+
+    await test_db.refresh(sub)
+    assert sub.status == "trialing"
+    assert sub.plan == "pro"
+    assert sub.current_period_end is not None

backend/tests/test_handoff_manager.py

@@ -1,8 +1,32 @@
 """Integration tests for HandoffManager service."""
+import asyncio
+from unittest.mock import AsyncMock, patch
+
 import pytest
 from httpx import AsyncClient
 
 from app.models.ai_session import AISession
+from app.models.user import User
+from app.services.handoff_manager import HandoffManager
+
+
+@pytest.fixture(autouse=True)
+def stub_ai_assessment():
+    """Keep handoff tests focused on handoff behavior, not external AI calls."""
+    with patch.object(
+        HandoffManager,
+        "_generate_handoff_summary",
+        new=AsyncMock(
+            return_value={
+                "summary_prose": "Stub escalation assessment",
+                "what_we_know": [],
+                "likely_cause": "Stub",
+                "suggested_steps": [],
+                "confidence": "medium",
+            }
+        ),
+    ):
+        yield
 
 
 @pytest.mark.asyncio
@@ -75,6 +99,56 @@ async def test_create_escalate_handoff(client: AsyncClient, test_user, auth_head
     assert session.status == "escalated"
     assert session.escalation_package is not None
     assert "branch_map" in session.escalation_package or "snapshot" in session.escalation_package
+    assert session.escalation_package["handoff_id"] == str(handoff.id)
+
+
+@pytest.mark.asyncio
+async def test_create_escalate_handoff_does_not_wait_on_slow_ai_assessment(
+    client: AsyncClient, test_user, auth_headers, test_db, monkeypatch
+):
+    """Escalate should commit a handoff even when optional AI assessment is slow."""
+    session = AISession(
+        user_id=test_user["user_data"]["id"],
+        account_id=test_user["user_data"]["account_id"],
+        session_type="guided",
+        intake_type="free_text",
+        intake_content={"text": "test"},
+        status="active",
+        confidence_tier="discovery",
+        conversation_messages=[],
+    )
+    test_db.add(session)
+    await test_db.flush()
+
+    async def slow_summary(self, session):
+        await asyncio.sleep(0.2)
+        return {"summary_prose": "too slow", "confidence": "medium"}
+
+    monkeypatch.setattr(
+        "app.services.handoff_manager.settings."
+        "ESCALATION_AI_ASSESSMENT_TIMEOUT_SECONDS",
+        0.01,
+    )
+    with patch.object(
+        HandoffManager,
+        "_generate_handoff_summary_inner",
+        new=slow_summary,
+    ):
+        manager = HandoffManager(test_db)
+        handoff = await manager.create_handoff(
+            session_id=session.id,
+            intent="escalate",
+            engineer_notes="Need senior help",
+            user_id=test_user["user_data"]["id"],
+        )
+
+    assert handoff.intent == "escalate"
+    assert handoff.ai_assessment is None
+    assert handoff.ai_assessment_data is None
+
+    await test_db.refresh(session)
+    assert session.status == "escalated"
+    assert session.handoff_count == 1
 
 
 @pytest.mark.asyncio
@@ -108,8 +182,399 @@ async def test_claim_session(client: AsyncClient, test_user, test_admin, auth_he
         claiming_user_id=test_admin["user_data"]["id"],
     )
 
-    assert claimed.claimed_by == test_admin["user_data"]["id"]
+    assert str(claimed.claimed_by) == test_admin["user_data"]["id"]
     assert claimed.claimed_at is not None
 
     await test_db.refresh(session)
     assert session.status == "active"
+
+
+@pytest.mark.asyncio
+async def test_claim_session_conflict_raises_already_claimed(
+    client: AsyncClient, test_user, test_admin, auth_headers, test_db
+):
+    """Two seniors claiming simultaneously: the second raises the typed
+    HandoffAlreadyClaimedError carrying the winner's identity. Without this
+    guard both calls would silently overwrite claimed_by — the locked
+    race-condition story depends on a real conflict response."""
+    from app.services.handoff_manager import (
+        HandoffAlreadyClaimedError,
+        HandoffManager,
+    )
+
+    session = AISession(
+        user_id=test_user["user_data"]["id"],
+        account_id=test_user["user_data"]["account_id"],
+        session_type="guided",
+        intake_type="free_text",
+        intake_content={"text": "test"},
+        status="active",
+        confidence_tier="discovery",
+        conversation_messages=[],
+    )
+    test_db.add(session)
+    loser = User(
+        email="race-loser@example.com",
+        password_hash="x",
+        name="Race Loser",
+        role="engineer",
+        account_id=test_user["user_data"]["account_id"],
+        account_role="engineer",
+    )
+    test_db.add(loser)
+    await test_db.flush()
+
+    manager = HandoffManager(test_db)
+    handoff = await manager.create_handoff(
+        session_id=session.id,
+        intent="escalate",
+        engineer_notes="Need help",
+        user_id=test_user["user_data"]["id"],
+    )
+
+    # First claim — admin wins.
+    await manager.claim_session(
+        handoff_id=handoff.id,
+        claiming_user_id=test_admin["user_data"]["id"],
+    )
+
+    # Second claim by a different user — standing in for the other senior who
+    # lost the race.
+    with pytest.raises(HandoffAlreadyClaimedError) as exc_info:
+        await manager.claim_session(
+            handoff_id=handoff.id,
+            claiming_user_id=loser.id,
+        )
+
+    err = exc_info.value
+    assert str(err.claimed_by_id) == test_admin["user_data"]["id"]
+    assert err.claimed_by_name  # populated from User.name
+    assert err.claimed_at is not None
+
+
+@pytest.mark.asyncio
+async def test_claim_session_idempotent_for_same_user(
+    client: AsyncClient, test_user, test_admin, auth_headers, test_db
+):
+    """A re-claim by the user who already won is a no-op, not a conflict.
+    Defends against double-clicks / network retries on the loser-side toast."""
+    session = AISession(
+        user_id=test_user["user_data"]["id"],
+        account_id=test_user["user_data"]["account_id"],
+        session_type="guided",
+        intake_type="free_text",
+        intake_content={"text": "test"},
+        status="active",
+        confidence_tier="discovery",
+        conversation_messages=[],
+    )
+    test_db.add(session)
+    await test_db.flush()
+
+    manager = HandoffManager(test_db)
+    handoff = await manager.create_handoff(
+        session_id=session.id,
+        intent="escalate",
+        engineer_notes="Need help",
+        user_id=test_user["user_data"]["id"],
+    )
+
+    first = await manager.claim_session(
+        handoff_id=handoff.id,
+        claiming_user_id=test_admin["user_data"]["id"],
+    )
+    second = await manager.claim_session(
+        handoff_id=handoff.id,
+        claiming_user_id=test_admin["user_data"]["id"],
+    )
+
+    assert str(first.claimed_by) == str(second.claimed_by) == test_admin["user_data"]["id"]
+
+
+@pytest.mark.asyncio
+async def test_claim_session_rejects_self_claim(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    """The engineer who escalated a session cannot pick up their own handoff."""
+    session = AISession(
+        user_id=test_user["user_data"]["id"],
+        account_id=test_user["user_data"]["account_id"],
+        session_type="guided",
+        intake_type="free_text",
+        intake_content={"text": "test"},
+        status="active",
+        confidence_tier="discovery",
+        conversation_messages=[],
+    )
+    test_db.add(session)
+    await test_db.flush()
+
+    manager = HandoffManager(test_db)
+    handoff = await manager.create_handoff(
+        session_id=session.id,
+        intent="escalate",
+        engineer_notes="Need help",
+        user_id=test_user["user_data"]["id"],
+    )
+
+    with pytest.raises(PermissionError):
+        await manager.claim_session(
+            handoff_id=handoff.id,
+            claiming_user_id=test_user["user_data"]["id"],
+        )
+
+
+# ─── Notification dispatch ────────────────────────────────────────────────────
+
+
+@pytest.mark.asyncio
+async def test_dispatch_emails_engineer_recipients_in_account(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    """dispatch_escalation_notifications emails every engineer/admin in the
+    account except the escalator."""
+    # Add a second user (engineer role) in the same account.
+    teammate = User(
+        email="teammate@example.com",
+        password_hash="x",
+        name="Teammate",
+        role="engineer",
+        account_id=test_user["user_data"]["account_id"],
+        account_role="engineer",
+    )
+    test_db.add(teammate)
+    await test_db.flush()
+
+    # Add a viewer-role user — must NOT receive a notification.
+    viewer = User(
+        email="viewer@example.com",
+        password_hash="x",
+        name="Viewer",
+        role="engineer",
+        account_id=test_user["user_data"]["account_id"],
+        account_role="viewer",
+    )
+    test_db.add(viewer)
+    await test_db.flush()
+
+    session = AISession(
+        user_id=test_user["user_data"]["id"],
+        account_id=test_user["user_data"]["account_id"],
+        session_type="guided",
+        intake_type="free_text",
+        intake_content={"text": "vpn down"},
+        problem_summary="VPN won't connect after Win update",
+        status="active",
+        confidence_tier="discovery",
+        conversation_messages=[],
+    )
+    test_db.add(session)
+    await test_db.commit()
+
+    manager = HandoffManager(test_db)
+    handoff = await manager.create_handoff(
+        session_id=session.id,
+        intent="escalate",
+        engineer_notes="Stuck on auth handshake",
+        user_id=test_user["user_data"]["id"],
+    )
+    await test_db.commit()
+
+    with patch(
+        "app.services.handoff_manager.EmailService.send_notification_email",
+        new=AsyncMock(return_value=True),
+    ) as send:
+        sent = await manager.dispatch_escalation_notifications(handoff)
+
+    assert sent == 1  # only the engineer-role teammate
+    recipients = {call.kwargs["to_email"] for call in send.call_args_list}
+    assert recipients == {"teammate@example.com"}
+    assert viewer.email not in recipients
+    assert test_user["email"] not in recipients  # not self-notified
+
+    title = send.call_args_list[0].kwargs["title"]
+    assert "VPN won't connect after Win update" in title
+
+
+@pytest.mark.asyncio
+async def test_dispatch_skipped_for_park_intent(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    """park-intent handoffs are private (waiting for client logs etc) — no
+    team-wide email."""
+    session = AISession(
+        user_id=test_user["user_data"]["id"],
+        account_id=test_user["user_data"]["account_id"],
+        session_type="guided",
+        intake_type="free_text",
+        intake_content={"text": "x"},
+        status="active",
+        confidence_tier="discovery",
+        conversation_messages=[],
+    )
+    test_db.add(session)
+    await test_db.commit()
+
+    manager = HandoffManager(test_db)
+    handoff = await manager.create_handoff(
+        session_id=session.id,
+        intent="park",
+        engineer_notes="waiting on customer",
+        user_id=test_user["user_data"]["id"],
+    )
+    await test_db.commit()
+
+    with patch(
+        "app.services.handoff_manager.EmailService.send_notification_email",
+        new=AsyncMock(return_value=True),
+    ) as send:
+        sent = await manager.dispatch_escalation_notifications(handoff)
+
+    assert sent == 0
+    assert send.call_count == 0
+
+
+@pytest.mark.asyncio
+async def test_dispatch_graceful_degradation_when_email_raises(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    """If the email service raises (auth misconfig, network, etc.), dispatch
+    must NOT raise. Handoff creation has already committed; emailing is
+    best-effort. Codex-flagged regression."""
+    teammate = User(
+        email="t@example.com",
+        password_hash="x",
+        name="T",
+        role="engineer",
+        account_id=test_user["user_data"]["account_id"],
+        account_role="engineer",
+    )
+    test_db.add(teammate)
+    await test_db.flush()
+
+    session = AISession(
+        user_id=test_user["user_data"]["id"],
+        account_id=test_user["user_data"]["account_id"],
+        session_type="guided",
+        intake_type="free_text",
+        intake_content={"text": "x"},
+        status="active",
+        confidence_tier="discovery",
+        conversation_messages=[],
+    )
+    test_db.add(session)
+    await test_db.commit()
+
+    manager = HandoffManager(test_db)
+    handoff = await manager.create_handoff(
+        session_id=session.id,
+        intent="escalate",
+        engineer_notes="help",
+        user_id=test_user["user_data"]["id"],
+    )
+    await test_db.commit()
+
+    with patch(
+        "app.services.handoff_manager.EmailService.send_notification_email",
+        new=AsyncMock(side_effect=RuntimeError("SMTP down")),
+    ):
+        # Must not raise.
+        sent = await manager.dispatch_escalation_notifications(handoff)
+    assert sent == 0
+
+
+@pytest.mark.asyncio
+async def test_dispatch_publishes_to_escalation_bus(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    """dispatch_escalation_notifications puts an event on the in-memory bus
+    so connected SSE subscribers see live arrivals."""
+    from app.core.escalation_bus import bus as escalation_bus
+
+    session = AISession(
+        user_id=test_user["user_data"]["id"],
+        account_id=test_user["user_data"]["account_id"],
+        session_type="guided",
+        intake_type="free_text",
+        intake_content={"text": "x"},
+        problem_summary="VPN down",
+        status="active",
+        confidence_tier="discovery",
+        conversation_messages=[],
+    )
+    test_db.add(session)
+    await test_db.commit()
+
+    manager = HandoffManager(test_db)
+    handoff = await manager.create_handoff(
+        session_id=session.id,
+        intent="escalate",
+        engineer_notes="please help",
+        user_id=test_user["user_data"]["id"],
+    )
+    await test_db.commit()
+
+    from uuid import UUID as PyUUID
+    account_id = PyUUID(test_user["user_data"]["account_id"])
+
+    queue = await escalation_bus.subscribe(account_id)
+    try:
+        with patch(
+            "app.services.handoff_manager.EmailService.send_notification_email",
+            new=AsyncMock(return_value=True),
+        ):
+            await manager.dispatch_escalation_notifications(handoff)
+
+        import asyncio
+        event = await asyncio.wait_for(queue.get(), timeout=1.0)
+        assert event["type"] == "handoff_created"
+        assert event["handoff_id"] == str(handoff.id)
+        assert event["session_id"] == str(session.id)
+        assert event["priority"] == "normal"
+    finally:
+        await escalation_bus.unsubscribe(account_id, queue)
+
+
+@pytest.mark.asyncio
+async def test_create_handoff_endpoint_dispatches_on_escalate(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    """End-to-end: POST /handoff with intent=escalate triggers
+    dispatch_escalation_notifications after commit. Verifies the wiring in
+    the endpoint, not just the manager method."""
+    teammate = User(
+        email="t2@example.com",
+        password_hash="x",
+        name="T2",
+        role="engineer",
+        account_id=test_user["user_data"]["account_id"],
+        account_role="engineer",
+    )
+    test_db.add(teammate)
+    await test_db.commit()
+
+    session = AISession(
+        user_id=test_user["user_data"]["id"],
+        account_id=test_user["user_data"]["account_id"],
+        session_type="guided",
+        intake_type="free_text",
+        intake_content={"text": "x"},
+        status="active",
+        confidence_tier="discovery",
+        conversation_messages=[],
+    )
+    test_db.add(session)
+    await test_db.commit()
+
+    with patch(
+        "app.services.handoff_manager.EmailService.send_notification_email",
+        new=AsyncMock(return_value=True),
+    ) as send:
+        resp = await client.post(
+            f"/api/v1/ai-sessions/{session.id}/handoff",
+            headers=auth_headers,
+            json={"intent": "escalate", "engineer_notes": "Need help"},
+        )
+    assert resp.status_code == 201
+    assert send.call_count == 1
+    assert send.call_args.kwargs["to_email"] == "t2@example.com"

backend/tests/test_kb_accelerator.py

@@ -13,6 +13,14 @@ pytestmark = pytest.mark.asyncio
 @pytest.fixture
 async def kb_setup(client, auth_headers, test_db):
     """Seed KB plan limits and return helpers."""
+    # KB tests were authored against a free-plan user. Phase 1 conftest seeds
+    # the test_user with a pro/active Subscription; downgrade to free here so
+    # quota numbers match the original test intent.
+    from app.models.subscription import Subscription
+    sub = (await test_db.execute(__import__("sqlalchemy").select(Subscription))).scalar_one()
+    sub.plan = "free"
+    await test_db.commit()
+
     # Update plan_limits with KB columns for 'free' plan
     await test_db.execute(
         __import__("sqlalchemy").text("""

backend/tests/test_oauth_callbacks.py

@@ -0,0 +1,120 @@
+import uuid
+import pytest
+from unittest.mock import patch
+from sqlalchemy import select
+from app.models.user import User
+from app.models.oauth_identity import OAuthIdentity
+from app.models.subscription import Subscription
+from app.services.oauth_providers import OAuthProfile
+
+
+@pytest.mark.asyncio
+async def test_google_callback_creates_user_account_subscription(
+    client, test_db, monkeypatch
+):
+    """Brand-new user via Google OAuth -> User + Account + Subscription + OAuthIdentity."""
+    from app.core.config import settings
+    monkeypatch.setattr(settings, "GOOGLE_CLIENT_ID", "client_dummy")
+    monkeypatch.setattr(settings, "GOOGLE_CLIENT_SECRET", "secret_dummy")
+
+    profile = OAuthProfile(
+        provider_subject="google_subject_123",
+        email="newuser@example.com",
+        name="New User",
+    )
+    with patch("app.api.endpoints.oauth.google_exchange_code", return_value=profile):
+        response = await client.post(
+            "/api/v1/auth/google/callback", json={"code": "auth_code_xyz"}
+        )
+    assert response.status_code == 200, response.json()
+    body = response.json()
+    assert body["is_new_user"] is True
+    assert body["access_token"]
+
+    user = (await test_db.execute(
+        select(User).where(User.email == "newuser@example.com")
+    )).scalar_one()
+    assert user.password_hash is None
+    assert user.email_verified_at is not None
+
+    identity = (await test_db.execute(
+        select(OAuthIdentity).where(OAuthIdentity.user_id == user.id)
+    )).scalar_one()
+    assert identity.provider == "google"
+    assert identity.provider_subject == "google_subject_123"
+
+    sub = (await test_db.execute(
+        select(Subscription).where(Subscription.account_id == user.account_id)
+    )).scalar_one()
+    assert sub.status == "trialing"
+    assert sub.plan == "pro"
+
+
+@pytest.mark.asyncio
+async def test_google_callback_existing_user_is_idempotent(
+    client, test_db, test_user, monkeypatch
+):
+    """When test_user's email is already registered, OAuth links + returns the
+    same user. Two calls with same provider_subject must not duplicate
+    OAuthIdentity rows."""
+    from app.core.config import settings
+    monkeypatch.setattr(settings, "GOOGLE_CLIENT_ID", "client_dummy")
+    monkeypatch.setattr(settings, "GOOGLE_CLIENT_SECRET", "secret_dummy")
+
+    user_id = uuid.UUID(test_user["user_data"]["id"])
+    email = test_user["email"]
+    name = test_user["user_data"]["name"]
+
+    profile = OAuthProfile(
+        provider_subject="google_subject_456",
+        email=email,
+        name=name,
+    )
+    with patch("app.api.endpoints.oauth.google_exchange_code", return_value=profile):
+        r1 = await client.post("/api/v1/auth/google/callback", json={"code": "x"})
+        r2 = await client.post("/api/v1/auth/google/callback", json={"code": "x"})
+    assert r1.status_code == 200
+    assert r2.status_code == 200
+    assert r1.json()["is_new_user"] is False
+    assert r2.json()["is_new_user"] is False
+
+    identities = (await test_db.execute(
+        select(OAuthIdentity).where(OAuthIdentity.user_id == user_id)
+    )).scalars().all()
+    assert len(identities) == 1
+
+
+@pytest.mark.asyncio
+async def test_google_callback_503_when_unconfigured(client, monkeypatch):
+    from app.core.config import settings
+    monkeypatch.setattr(settings, "GOOGLE_CLIENT_ID", None)
+
+    response = await client.post(
+        "/api/v1/auth/google/callback", json={"code": "x"}
+    )
+    assert response.status_code == 503
+
+
+@pytest.mark.asyncio
+async def test_microsoft_callback_creates_user(client, test_db, monkeypatch):
+    from app.core.config import settings
+    monkeypatch.setattr(settings, "MS_CLIENT_ID", "client_dummy")
+    monkeypatch.setattr(settings, "MS_CLIENT_SECRET", "secret_dummy")
+
+    profile = OAuthProfile(
+        provider_subject="ms_subject_789",
+        email="msuser@example.com",
+        name="MS User",
+    )
+    with patch("app.api.endpoints.oauth.microsoft_exchange_code", return_value=profile):
+        response = await client.post(
+            "/api/v1/auth/microsoft/callback", json={"code": "auth_code"}
+        )
+    assert response.status_code == 200, response.json()
+    user = (await test_db.execute(
+        select(User).where(User.email == "msuser@example.com")
+    )).scalar_one()
+    identity = (await test_db.execute(
+        select(OAuthIdentity).where(OAuthIdentity.user_id == user.id)
+    )).scalar_one()
+    assert identity.provider == "microsoft"

backend/tests/test_oauth_identity_model.py

@@ -0,0 +1,39 @@
+import uuid
+
+import pytest
+from sqlalchemy import select
+
+from app.models.oauth_identity import OAuthIdentity
+
+
+@pytest.mark.asyncio
+async def test_oauth_identity_unique_provider_subject(test_db, test_user):
+    """Two rows with same provider+subject should violate uniqueness."""
+    user_id = uuid.UUID(test_user["user_data"]["id"])
+
+    row1 = OAuthIdentity(
+        user_id=user_id,
+        provider="google",
+        provider_subject="abc-123",
+        provider_email_at_link="alex@acmemsp.com",
+    )
+    test_db.add(row1)
+    await test_db.commit()
+
+    row2 = OAuthIdentity(
+        user_id=user_id,
+        provider="google",
+        provider_subject="abc-123",
+        provider_email_at_link="alex@acmemsp.com",
+    )
+    test_db.add(row2)
+    with pytest.raises(Exception):  # IntegrityError
+        await test_db.commit()
+    await test_db.rollback()
+
+    rows = (
+        await test_db.execute(
+            select(OAuthIdentity).where(OAuthIdentity.user_id == user_id)
+        )
+    ).scalars().all()
+    assert len(rows) == 1

backend/tests/test_oauth_only_user_paths.py

@@ -0,0 +1,83 @@
+import uuid
+import pytest
+from sqlalchemy import select
+from app.models.user import User
+from app.models.account import Account
+from app.models.oauth_identity import OAuthIdentity
+
+
+async def _make_oauth_only_user(test_db, email, *, with_identity=True):
+    """Create an OAuth-only user (password_hash=None) directly in the test DB."""
+    import secrets
+    account = Account(
+        name=f"{email}-acct",
+        display_code=secrets.token_hex(4).upper(),
+    )
+    test_db.add(account)
+    await test_db.flush()
+    user = User(
+        email=email,
+        name="OAuth User",
+        password_hash=None,
+        account_id=account.id,
+        account_role="owner",
+    )
+    test_db.add(user)
+    await test_db.flush()
+    if with_identity:
+        test_db.add(OAuthIdentity(
+            user_id=user.id, provider="google",
+            provider_subject=f"google_{email}",
+            provider_email_at_link=email,
+        ))
+    await test_db.commit()
+    return user
+
+
+@pytest.mark.asyncio
+async def test_login_form_rejects_oauth_only_user_with_helpful_error(client, test_db):
+    await _make_oauth_only_user(test_db, "oauth-only@example.com")
+    response = await client.post(
+        "/api/v1/auth/login",
+        data={"username": "oauth-only@example.com", "password": "wontwork"},
+    )
+    assert response.status_code == 400
+    body = response.json()
+    assert body["detail"]["error"] == "use_oauth_provider"
+    assert "google" in body["detail"]["providers"]
+
+
+@pytest.mark.asyncio
+async def test_login_json_rejects_oauth_only_user(client, test_db):
+    await _make_oauth_only_user(test_db, "oauth-only2@example.com")
+    response = await client.post(
+        "/api/v1/auth/login/json",
+        json={"email": "oauth-only2@example.com", "password": "wontwork"},
+    )
+    assert response.status_code == 400
+    assert response.json()["detail"]["error"] == "use_oauth_provider"
+
+
+@pytest.mark.asyncio
+async def test_password_forgot_silent_for_oauth_only_user(client, test_db):
+    """OAuth-only users get the generic message; no email is sent."""
+    await _make_oauth_only_user(test_db, "oauth-forgot@example.com", with_identity=False)
+    from unittest.mock import AsyncMock, patch
+    with patch("app.core.email.EmailService.send_password_reset_email", new_callable=AsyncMock) as mock_send:
+        response = await client.post(
+            "/api/v1/auth/password/forgot",
+            json={"email": "oauth-forgot@example.com"},
+        )
+    assert response.status_code == 200
+    mock_send.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_login_for_password_user_still_works(client, test_user):
+    """Regression: existing password-based login must still succeed."""
+    response = await client.post(
+        "/api/v1/auth/login/json",
+        json={"email": test_user["email"], "password": test_user["password"]},
+    )
+    assert response.status_code == 200
+    assert response.json()["access_token"]

backend/tests/test_pilot_complimentary_backfill.py

@@ -0,0 +1,85 @@
+"""Smoke test for the complimentary backfill: assertions about the post-state.
+The actual migration runs at deploy time; tests use create_all so the
+migration body isn't executed automatically. We invoke the SQL inline to
+exercise the same effect."""
+import uuid
+import pytest
+from sqlalchemy import select, text, delete
+from app.models.account import Account
+from app.models.subscription import Subscription
+
+
+@pytest.mark.asyncio
+async def test_complimentary_backfill_sets_status_and_inserts_missing_rows(test_db):
+    """Inline-run the backfill SQL and assert post-state."""
+    # Seed a fresh account with no subscription
+    no_sub_account = Account(name="NoSub", display_code="NOSUB001")
+    test_db.add(no_sub_account)
+    await test_db.flush()
+
+    # Seed an account with a trialing subscription (should become complimentary)
+    trial_account = Account(name="Trial", display_code="TRIAL001")
+    test_db.add(trial_account)
+    await test_db.flush()
+    test_db.add(Subscription(
+        account_id=trial_account.id, plan="free", status="trialing",
+    ))
+
+    # Seed an account with a canceled subscription (should be preserved)
+    canceled_account = Account(name="Cancel", display_code="CANCL001")
+    test_db.add(canceled_account)
+    await test_db.flush()
+    test_db.add(Subscription(
+        account_id=canceled_account.id, plan="pro", status="canceled",
+    ))
+    await test_db.commit()
+
+    # Run the same SQL the migration runs
+    await test_db.execute(text("""
+        UPDATE subscriptions
+        SET status = 'complimentary', plan = 'pro',
+            current_period_end = NULL, current_period_start = NULL,
+            updated_at = now()
+        WHERE status NOT IN ('canceled', 'past_due')
+    """))
+    await test_db.execute(text("""
+        INSERT INTO subscriptions (id, account_id, plan, status, cancel_at_period_end, created_at, updated_at)
+        SELECT gen_random_uuid(), a.id, 'pro', 'complimentary', false, now(), now()
+        FROM accounts a
+        WHERE NOT EXISTS (SELECT 1 FROM subscriptions s WHERE s.account_id = a.id)
+    """))
+    await test_db.commit()
+
+    # All three accounts now have a Subscription
+    no_sub_row = (await test_db.execute(
+        select(Subscription).where(Subscription.account_id == no_sub_account.id)
+    )).scalar_one()
+    assert no_sub_row.status == "complimentary"
+    assert no_sub_row.plan == "pro"
+
+    trial_row = (await test_db.execute(
+        select(Subscription).where(Subscription.account_id == trial_account.id)
+    )).scalar_one()
+    assert trial_row.status == "complimentary"
+    assert trial_row.plan == "pro"
+
+    canceled_row = (await test_db.execute(
+        select(Subscription).where(Subscription.account_id == canceled_account.id)
+    )).scalar_one()
+    # Canceled is preserved
+    assert canceled_row.status == "canceled"
+    assert canceled_row.plan == "pro"
+
+
+@pytest.mark.asyncio
+async def test_complimentary_subscription_passes_active_subscription_guard(
+    client, test_db, test_user, auth_headers
+):
+    """The require_active_subscription guard accepts complimentary status."""
+    account_id = uuid.UUID(test_user["user_data"]["account_id"])
+    await test_db.execute(delete(Subscription).where(Subscription.account_id == account_id))
+    test_db.add(Subscription(account_id=account_id, plan="pro", status="complimentary"))
+    await test_db.commit()
+
+    response = await client.get("/api/v1/trees", headers=auth_headers)
+    assert response.status_code != 402

backend/tests/test_session_handoffs_api.py

@@ -1,8 +1,41 @@
 """API endpoint tests for session handoffs."""
+from unittest.mock import AsyncMock, patch
+from uuid import UUID as PyUUID
+
 import pytest
 from httpx import AsyncClient
+from sqlalchemy import select
 
+from app.api.endpoints.session_handoffs import stream_escalations
+from app.core.escalation_bus import bus as escalation_bus
 from app.models.ai_session import AISession
+from app.models.session_handoff import SessionHandoff
+from app.models.user import User
+from app.services.handoff_manager import HandoffManager
+
+
+class _ConnectedRequest:
+    async def is_disconnected(self) -> bool:
+        return False
+
+
+@pytest.fixture(autouse=True)
+def stub_ai_assessment():
+    """Endpoint tests should not wait on the external AI assessment path."""
+    with patch.object(
+        HandoffManager,
+        "_generate_handoff_summary",
+        new=AsyncMock(
+            return_value={
+                "summary_prose": "Stub escalation assessment",
+                "what_we_know": [],
+                "likely_cause": "Stub",
+                "suggested_steps": [],
+                "confidence": "medium",
+            }
+        ),
+    ):
+        yield
 
 
 @pytest.mark.asyncio
@@ -58,3 +91,234 @@ async def test_get_queue(client: AsyncClient, test_user, auth_headers, test_db):
     assert resp.status_code == 200
     data = resp.json()
     assert len(data) >= 1
+
+
+@pytest.mark.asyncio
+async def test_claim_blocked_for_viewer_role(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    """POST /handoffs/{id}/claim must 403 for viewer-role users.
+
+    Codex review flagged the missing role gate as wedge-relevant: the
+    race-condition story (two seniors clicking Pick Up simultaneously)
+    requires auth gating for audit integrity. Viewers must not be able
+    to claim escalations.
+    """
+    # Create a session + handoff as the engineer-role test_user (default = owner).
+    session = AISession(
+        user_id=test_user["user_data"]["id"],
+        account_id=test_user["user_data"]["account_id"],
+        session_type="guided",
+        intake_type="free_text",
+        intake_content={"text": "test"},
+        status="active",
+        confidence_tier="discovery",
+        conversation_messages=[],
+    )
+    test_db.add(session)
+    await test_db.commit()
+
+    create_resp = await client.post(
+        f"/api/v1/ai-sessions/{session.id}/handoff",
+        headers=auth_headers,
+        json={"intent": "escalate", "engineer_notes": "Need help"},
+    )
+    assert create_resp.status_code == 201
+    handoff_id = create_resp.json()["id"]
+
+    # Downgrade the user to viewer.
+    user_id = PyUUID(test_user["user_data"]["id"])
+    user = (
+        await test_db.execute(select(User).where(User.id == user_id))
+    ).scalar_one()
+    user.account_role = "viewer"
+    await test_db.commit()
+
+    claim_resp = await client.post(
+        f"/api/v1/ai-sessions/{session.id}/handoffs/{handoff_id}/claim",
+        headers=auth_headers,
+    )
+    assert claim_resp.status_code == 403
+    assert "engineer" in claim_resp.json()["detail"].lower()
+
+
+@pytest.mark.asyncio
+async def test_escalations_stream_blocked_for_viewer(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    """SSE stream is role-gated to engineer-or-admin (matches queue/claim)."""
+    user_id = PyUUID(test_user["user_data"]["id"])
+    user = (
+        await test_db.execute(select(User).where(User.id == user_id))
+    ).scalar_one()
+    user.account_role = "viewer"
+    await test_db.commit()
+
+    resp = await client.get(
+        "/api/v1/ai-sessions/escalations/stream", headers=auth_headers
+    )
+    assert resp.status_code == 403
+
+
+@pytest.mark.asyncio
+async def test_escalations_stream_returns_sse_content_type(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    """Engineer/owner can open the SSE stream and gets text/event-stream
+    plus an initial `ready` event. Read just enough bytes to confirm the
+    handshake — the full pub/sub flow is covered by the bus + dispatcher tests
+    separately.
+
+    Do not use `client.stream()` here: HTTPX's ASGITransport buffers the whole
+    response body before returning, which hangs forever for an infinite SSE
+    stream.
+    """
+    user_id = PyUUID(test_user["user_data"]["id"])
+    user = (
+        await test_db.execute(select(User).where(User.id == user_id))
+    ).scalar_one()
+
+    resp = await stream_escalations(_ConnectedRequest(), current_user=user)
+    assert resp.media_type == "text/event-stream"
+
+    body_iterator = resp.body_iterator
+    try:
+        first = await anext(body_iterator)
+    finally:
+        await body_iterator.aclose()
+
+    assert "event: ready" in first
+    assert '"account_id"' in first
+    assert escalation_bus.subscriber_count(user.account_id) == 0
+
+
+@pytest.mark.asyncio
+async def test_claim_allowed_for_engineer_role(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    """POST /handoffs/{id}/claim succeeds for engineer-or-admin roles."""
+    original_engineer = User(
+        email="original-engineer@example.com",
+        password_hash="x",
+        name="Original Engineer",
+        role="engineer",
+        account_id=test_user["user_data"]["account_id"],
+        account_role="engineer",
+    )
+    test_db.add(original_engineer)
+    await test_db.flush()
+
+    session = AISession(
+        user_id=original_engineer.id,
+        account_id=test_user["user_data"]["account_id"],
+        session_type="guided",
+        intake_type="free_text",
+        intake_content={"text": "test"},
+        status="active",
+        confidence_tier="discovery",
+        conversation_messages=[],
+    )
+    test_db.add(session)
+    await test_db.flush()
+
+    handoff = SessionHandoff(
+        session_id=session.id,
+        account_id=test_user["user_data"]["account_id"],
+        handed_off_by=original_engineer.id,
+        intent="escalate",
+        snapshot={"problem_summary": "test"},
+        engineer_notes="Need help",
+    )
+    test_db.add(handoff)
+    await test_db.commit()
+
+    # Default test_user role is "owner", which passes engineer-or-admin.
+    claim_resp = await client.post(
+        f"/api/v1/ai-sessions/{session.id}/handoffs/{handoff.id}/claim",
+        headers=auth_headers,
+    )
+    assert claim_resp.status_code == 200
+    assert claim_resp.json()["claimed_by"] == test_user["user_data"]["id"]
+    assert claim_resp.json()["claimed_at"] is not None
+
+
+@pytest.mark.asyncio
+async def test_claim_rejects_self_claim(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    """POST /handoffs/{id}/claim returns 403 for the original escalator."""
+    session = AISession(
+        user_id=test_user["user_data"]["id"],
+        account_id=test_user["user_data"]["account_id"],
+        session_type="guided",
+        intake_type="free_text",
+        intake_content={"text": "test"},
+        status="escalated",
+        confidence_tier="discovery",
+        conversation_messages=[],
+    )
+    test_db.add(session)
+    await test_db.flush()
+
+    handoff = SessionHandoff(
+        session_id=session.id,
+        account_id=test_user["user_data"]["account_id"],
+        handed_off_by=test_user["user_data"]["id"],
+        intent="escalate",
+        snapshot={"problem_summary": "test"},
+        engineer_notes="Need help",
+    )
+    test_db.add(handoff)
+    await test_db.commit()
+
+    claim_resp = await client.post(
+        f"/api/v1/ai-sessions/{session.id}/handoffs/{handoff.id}/claim",
+        headers=auth_headers,
+    )
+    assert claim_resp.status_code == 403
+    assert "own handoff" in claim_resp.json()["detail"]
+
+
+@pytest.mark.asyncio
+async def test_escalation_queue_excludes_own_escalations(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    """The post-escalation dashboard queue should not show your own handoff."""
+    own_session = AISession(
+        user_id=test_user["user_data"]["id"],
+        account_id=test_user["user_data"]["account_id"],
+        session_type="chat",
+        intake_type="free_text",
+        intake_content={"text": "own"},
+        status="escalated",
+        confidence_tier="discovery",
+        conversation_messages=[],
+    )
+    other_engineer = User(
+        email="other-engineer@example.com",
+        password_hash="x",
+        name="Other Engineer",
+        role="engineer",
+        account_id=test_user["user_data"]["account_id"],
+        account_role="engineer",
+    )
+    test_db.add_all([own_session, other_engineer])
+    await test_db.flush()
+    other_session = AISession(
+        user_id=other_engineer.id,
+        account_id=test_user["user_data"]["account_id"],
+        session_type="chat",
+        intake_type="free_text",
+        intake_content={"text": "other"},
+        status="escalated",
+        confidence_tier="discovery",
+        conversation_messages=[],
+    )
+    test_db.add(other_session)
+    await test_db.commit()
+
+    resp = await client.get("/api/v1/ai-sessions/escalation-queue", headers=auth_headers)
+    assert resp.status_code == 200
+    ids = {item["id"] for item in resp.json()}
+    assert str(own_session.id) not in ids
+    assert str(other_session.id) in ids

backend/tests/test_stripe_webhook_handler.py

@@ -0,0 +1,144 @@
+import json
+import uuid
+import pytest
+from sqlalchemy import delete, select
+from unittest.mock import patch
+from app.models.subscription import Subscription
+
+
+def _make_event(event_id, event_type, obj):
+    return {
+        "id": event_id,
+        "type": event_type,
+        "data": {"object": obj},
+    }
+
+
+@pytest.mark.asyncio
+async def test_checkout_completed_activates_subscription(
+    client, test_db, test_user, auth_headers, monkeypatch
+):
+    from app.core.config import settings
+    monkeypatch.setattr(settings, "STRIPE_SECRET_KEY", "sk_test_dummy")
+    monkeypatch.setattr(settings, "STRIPE_WEBHOOK_SECRET", "whsec_dummy")
+
+    account_id = uuid.UUID(test_user["user_data"]["account_id"])
+    # Replace seeded sub with trialing + stripe_customer_id linkage
+    from app.models.account import Account
+    account = (await test_db.execute(select(Account).where(Account.id == account_id))).scalar_one()
+    account.stripe_customer_id = "cus_xxx"
+    await test_db.execute(delete(Subscription).where(Subscription.account_id == account_id))
+    test_db.add(Subscription(account_id=account_id, plan="pro", status="trialing"))
+    await test_db.commit()
+
+    event = _make_event("evt_co_1", "checkout.session.completed", {
+        "id": "cs_xxx",
+        "customer": "cus_xxx",
+        "subscription": "sub_xxx",
+    })
+
+    with patch("stripe.Subscription.retrieve", return_value={
+        "id": "sub_xxx",
+        "status": "active",
+        "current_period_start": 1714521600,
+        "current_period_end": 1717113600,
+        "items": {"data": [{
+            "price": {"id": "price_test_monthly"},
+            "quantity": 5,
+        }]},
+        "cancel_at_period_end": False,
+    }), patch("stripe.Webhook.construct_event", return_value=event):
+        response = await client.post(
+            "/api/v1/webhooks/stripe",
+            content=json.dumps(event),
+            headers={"stripe-signature": "fake-sig"},
+        )
+    assert response.status_code == 200, response.json()
+
+    sub = (await test_db.execute(
+        select(Subscription).where(Subscription.account_id == account_id)
+    )).scalar_one()
+    assert sub.status == "active"
+    assert sub.stripe_subscription_id == "sub_xxx"
+
+
+@pytest.mark.asyncio
+async def test_subscription_deleted_cancels_account(
+    client, test_db, test_user, auth_headers, monkeypatch
+):
+    from app.core.config import settings
+    monkeypatch.setattr(settings, "STRIPE_SECRET_KEY", "sk_test_dummy")
+    monkeypatch.setattr(settings, "STRIPE_WEBHOOK_SECRET", "whsec_dummy")
+
+    account_id = uuid.UUID(test_user["user_data"]["account_id"])
+    await test_db.execute(delete(Subscription).where(Subscription.account_id == account_id))
+    test_db.add(Subscription(
+        account_id=account_id, plan="pro", status="active",
+        stripe_subscription_id="sub_xxx",
+    ))
+    await test_db.commit()
+
+    event = _make_event("evt_del_1", "customer.subscription.deleted", {
+        "id": "sub_xxx",
+        "current_period_start": 1714521600,
+        "current_period_end": 1717113600,
+        "items": {"data": [{"quantity": 1}]},
+    })
+
+    with patch("stripe.Webhook.construct_event", return_value=event):
+        response = await client.post(
+            "/api/v1/webhooks/stripe",
+            content=json.dumps(event),
+            headers={"stripe-signature": "fake-sig"},
+        )
+    assert response.status_code == 200
+
+    sub = (await test_db.execute(
+        select(Subscription).where(Subscription.account_id == account_id)
+    )).scalar_one()
+    assert sub.status == "canceled"
+
+
+@pytest.mark.asyncio
+async def test_webhook_signature_failure_returns_400(client, monkeypatch):
+    from app.core.config import settings
+    monkeypatch.setattr(settings, "STRIPE_SECRET_KEY", "sk_test_dummy")
+    monkeypatch.setattr(settings, "STRIPE_WEBHOOK_SECRET", "whsec_dummy")
+
+    with patch("stripe.Webhook.construct_event", side_effect=ValueError("bad sig")):
+        response = await client.post(
+            "/api/v1/webhooks/stripe",
+            content=b"{}",
+            headers={"stripe-signature": "fake-sig"},
+        )
+    assert response.status_code == 400
+
+
+@pytest.mark.asyncio
+async def test_webhook_idempotency(
+    client, test_db, test_user, auth_headers, monkeypatch
+):
+    from app.core.config import settings
+    monkeypatch.setattr(settings, "STRIPE_SECRET_KEY", "sk_test_dummy")
+    monkeypatch.setattr(settings, "STRIPE_WEBHOOK_SECRET", "whsec_dummy")
+
+    account_id = uuid.UUID(test_user["user_data"]["account_id"])
+    await test_db.execute(delete(Subscription).where(Subscription.account_id == account_id))
+    test_db.add(Subscription(account_id=account_id, plan="pro", status="trialing"))
+    await test_db.commit()
+
+    event = _make_event("evt_dup_1", "customer.subscription.updated", {
+        "id": "sub_yyy",
+        "status": "active",
+        "current_period_start": 1714521600,
+        "current_period_end": 1717113600,
+        "items": {"data": [{"quantity": 1}]},
+        "cancel_at_period_end": False,
+    })
+    with patch("stripe.Webhook.construct_event", return_value=event):
+        r1 = await client.post("/api/v1/webhooks/stripe", content=json.dumps(event), headers={"stripe-signature": "x"})
+        r2 = await client.post("/api/v1/webhooks/stripe", content=json.dumps(event), headers={"stripe-signature": "x"})
+    assert r1.status_code == 200
+    assert r2.status_code == 200
+    assert r1.json()["applied"] is True
+    assert r2.json()["applied"] is False

backend/tests/test_subscription_guards.py

@@ -0,0 +1,89 @@
+"""Tests for require_active_subscription dependency.
+
+Verifies the 402 gating logic for Pro-guarded routers and the allowlist
+that lets billing/account/auth flows through even when locked.
+"""
+
+import uuid
+import pytest
+from datetime import datetime, timezone, timedelta
+from sqlalchemy import delete
+from app.models.subscription import Subscription
+
+
+async def _set_subscription(test_db, account_id, **fields):
+    """Replace any existing Subscription on the account with one matching `fields`."""
+    await test_db.execute(delete(Subscription).where(Subscription.account_id == account_id))
+    test_db.add(Subscription(account_id=account_id, **fields))
+    await test_db.commit()
+
+
+@pytest.mark.asyncio
+async def test_active_subscription_passes(client, test_db, test_user, auth_headers):
+    account_id = uuid.UUID(test_user["user_data"]["account_id"])
+    await _set_subscription(test_db, account_id, plan="pro", status="active")
+    response = await client.get("/api/v1/trees", headers=auth_headers)
+    assert response.status_code != 402
+
+
+@pytest.mark.asyncio
+async def test_complimentary_subscription_passes(client, test_db, test_user, auth_headers):
+    account_id = uuid.UUID(test_user["user_data"]["account_id"])
+    await _set_subscription(test_db, account_id, plan="pro", status="complimentary")
+    response = await client.get("/api/v1/trees", headers=auth_headers)
+    assert response.status_code != 402
+
+
+@pytest.mark.asyncio
+async def test_trialing_unexpired_passes(client, test_db, test_user, auth_headers):
+    account_id = uuid.UUID(test_user["user_data"]["account_id"])
+    await _set_subscription(
+        test_db, account_id,
+        plan="pro", status="trialing",
+        current_period_end=datetime.now(timezone.utc) + timedelta(days=5),
+    )
+    response = await client.get("/api/v1/trees", headers=auth_headers)
+    assert response.status_code != 402
+
+
+@pytest.mark.asyncio
+async def test_trialing_expired_returns_402(client, test_db, test_user, auth_headers):
+    account_id = uuid.UUID(test_user["user_data"]["account_id"])
+    await _set_subscription(
+        test_db, account_id,
+        plan="pro", status="trialing",
+        current_period_end=datetime.now(timezone.utc) - timedelta(hours=1),
+    )
+    response = await client.get("/api/v1/trees", headers=auth_headers)
+    assert response.status_code == 402
+    body = response.json()
+    assert body["detail"]["error"] == "subscription_inactive"
+
+
+@pytest.mark.asyncio
+async def test_canceled_returns_402(client, test_db, test_user, auth_headers):
+    account_id = uuid.UUID(test_user["user_data"]["account_id"])
+    await _set_subscription(test_db, account_id, plan="pro", status="canceled")
+    response = await client.get("/api/v1/trees", headers=auth_headers)
+    assert response.status_code == 402
+
+
+@pytest.mark.asyncio
+async def test_no_subscription_returns_402(client, test_db, test_user, auth_headers):
+    account_id = uuid.UUID(test_user["user_data"]["account_id"])
+    # Remove the seeded default subscription
+    await test_db.execute(delete(Subscription).where(Subscription.account_id == account_id))
+    await test_db.commit()
+    response = await client.get("/api/v1/trees", headers=auth_headers)
+    assert response.status_code == 402
+    body = response.json()
+    assert body["detail"]["error"] == "no_subscription"
+
+
+@pytest.mark.asyncio
+async def test_auth_me_bypasses_guard(client, test_db, test_user, auth_headers):
+    """Allowlisted route works even when subscription is canceled."""
+    account_id = uuid.UUID(test_user["user_data"]["account_id"])
+    await _set_subscription(test_db, account_id, plan="pro", status="canceled")
+    response = await client.get("/api/v1/auth/me", headers=auth_headers)
+    assert response.status_code == 200

backend/tests/test_subscription_limits.py

@@ -10,8 +10,15 @@ class TestSubscriptionLimits:
     """Test suite for subscription plan limits."""
 
     @pytest.mark.asyncio
-    async def test_free_plan_tree_limit(self, client: AsyncClient, auth_headers: dict):
+    async def test_free_plan_tree_limit(
+        self, client: AsyncClient, auth_headers: dict, test_db: AsyncSession
+    ):
         """Test that free plan has tree creation limit of 3."""
+        from app.models.subscription import Subscription
+        sub = (await test_db.execute(select(Subscription))).scalar_one()
+        sub.plan = "free"
+        await test_db.commit()
+
         tree_template = {
             "name": "Limit Test Tree",
             "tree_structure": {
@@ -90,8 +97,15 @@ class TestSubscriptionLimits:
             assert response.status_code == 201
 
     @pytest.mark.asyncio
-    async def test_free_plan_limits_correct(self, client: AsyncClient, auth_headers: dict):
+    async def test_free_plan_limits_correct(
+        self, client: AsyncClient, auth_headers: dict, test_db: AsyncSession
+    ):
         """Test that free plan limits are correct."""
+        from app.models.subscription import Subscription
+        sub = (await test_db.execute(select(Subscription))).scalar_one()
+        sub.plan = "free"
+        await test_db.commit()
+
         response = await client.get("/api/v1/accounts/me/subscription", headers=auth_headers)
         assert response.status_code == 200
         limits = response.json()["limits"]

backend/tests/test_subscription_properties.py

@@ -0,0 +1,41 @@
+from datetime import datetime, timezone, timedelta
+from app.models.subscription import Subscription
+
+
+def make_sub(**kwargs):
+    sub = Subscription()
+    sub.plan = kwargs.get("plan", "free")
+    sub.status = kwargs.get("status", "active")
+    sub.current_period_end = kwargs.get("current_period_end")
+    return sub
+
+
+def test_complimentary_is_active_but_not_paid():
+    sub = make_sub(plan="pro", status="complimentary")
+    assert sub.is_active is True
+    assert sub.is_paid is False
+    assert sub.has_pro_entitlement is True
+
+
+def test_paid_pro_active():
+    sub = make_sub(plan="pro", status="active")
+    assert sub.is_paid is True
+    assert sub.has_pro_entitlement is True
+
+
+def test_trial_unexpired_has_entitlement():
+    sub = make_sub(plan="pro", status="trialing", current_period_end=datetime.now(timezone.utc) + timedelta(days=5))
+    assert sub.is_active is True
+    assert sub.is_paid is False
+    assert sub.has_pro_entitlement is True
+
+
+def test_trial_expired_no_entitlement():
+    sub = make_sub(plan="pro", status="trialing", current_period_end=datetime.now(timezone.utc) - timedelta(hours=1))
+    assert sub.has_pro_entitlement is False
+
+
+def test_canceled_no_entitlement():
+    sub = make_sub(plan="pro", status="canceled")
+    assert sub.is_active is False
+    assert sub.has_pro_entitlement is False

backend/tests/test_tenant_isolation_p0.py

@@ -12,13 +12,18 @@ from sqlalchemy.ext.asyncio import AsyncSession
 from app.models.account import Account
 from app.models.user import User
 from app.models.tree import Tree
+from app.models.subscription import Subscription
 from app.core.security import get_password_hash
 
 
 # ── Helpers ──────────────────────────────────────────────────────────────────
 
 async def _create_account_and_user(db: AsyncSession, prefix: str):
-    """Create a fresh account + engineer user. Returns (account, user, plain_password)."""
+    """Create a fresh account + engineer user. Returns (account, user, plain_password).
+
+    Seeds a default active Pro Subscription for the account so requests pass
+    the require_active_subscription guard added in Phase 1 Task 11.
+    """
     password = "TestPass123!"
     account = Account(
         name=f"{prefix}-corp",
@@ -36,6 +41,7 @@ async def _create_account_and_user(db: AsyncSession, prefix: str):
         account_role="engineer",
     )
     db.add(user)
+    db.add(Subscription(account_id=account.id, plan="pro", status="active"))
     await db.flush()
     return account, user, password
 
@@ -168,6 +174,7 @@ async def test_ai_session_search_cannot_see_other_users_sessions(
     account = Account(name="Shared Corp", display_code=uuid.uuid4().hex[:8])
     test_db.add(account)
     await test_db.flush()
+    test_db.add(Subscription(account_id=account.id, plan="pro", status="active"))
 
     password = "TestPass123!"
     user_a = User(

backend/tests/test_user_password_nullable.py

@@ -0,0 +1,23 @@
+import pytest
+from app.models.user import User
+from app.models.account import Account
+
+
+@pytest.mark.asyncio
+async def test_user_can_be_created_without_password_hash(test_db):
+    """OAuth-only users have password_hash=None and the row should commit cleanly."""
+    account = Account(name="OAuthShop", display_code="OAUTH001")
+    test_db.add(account)
+    await test_db.flush()
+
+    user = User(
+        email="oauth-only@example.com",
+        name="OAuth Only",
+        password_hash=None,
+        account_id=account.id,
+        account_role="engineer",
+    )
+    test_db.add(user)
+    await test_db.commit()
+    await test_db.refresh(user)
+    assert user.password_hash is None

docs/plans/2026-04-27-escalation-mode-wedge-design.md

@@ -0,0 +1,494 @@
+# Design: ResolutionFlow GTM — Escalation-Mode-First Wedge
+
+Generated by /office-hours on 2026-04-26
+Branch: main
+Repo: chihlasm/resolutionflow
+Status: APPROVED
+Mode: Startup
+
+## Problem Statement
+
+ResolutionFlow is a multi-tenant SaaS troubleshooting platform for MSPs, currently
+in Go-to-Market Validation (pre-PMF). The backend is feature-complete (55+ endpoints,
+100+ tests, FlowPilot telemetry baseline accruing). The product has users but no
+paying customers.
+
+The blocker is not engineering completeness. The blocker is the absence of a sharp
+GTM story tied to a number a buyer can verify. The session reframed the wedge twice
+before landing on the real one.
+
+**What ResolutionFlow actually is:** the structuring layer between conversational AI
+and the way MSP techs work tickets. AI is great at producing answers; it is bad at
+producing workflow-shaped output. ResolutionFlow gives the tech the AI they already
+trust (Claude/GPT) but organizes the output into actionable structured steps,
+records the session, captures customer-specific context, and turns the result into
+PSA-formatted ticket notes — and optionally a runbook — without the tech writing
+anything.
+
+**Positioning line:** "the senior engineer looking over your shoulder."
+
+## Demand Evidence
+
+The founder is the first user. Senior Systems Engineer at an MSP, losing ~20
+hours/week to cross-domain interruptions (systems engineer pulled into networking
+problems and vice versa). At least 4 interruptions per day, with the time cost
+concentrated in the gap between AI-conversation output and MSP-ticket workflow.
+
+This is solving-your-own-problem demand evidence — strongest possible signal at
+this stage. The 20 hrs/week figure is the founder's own time, not a hypothetical.
+Every MSP shop with a senior tech and a junior tech has a version of this problem.
+
+Telemetry signal (Phase 0.5 baseline accruing): captured flows pile up but are not
+being re-used. This says capture works, retrieval doesn't — which means the
+"hours-saved-via-re-use" number isn't yet generatable from existing data. The
+GTM-grade ROI story needs a different metric until re-use lands: minutes recovered
+per escalation, generated by Approach A below.
+
+## Status Quo
+
+MSP techs today resolve tickets via three workarounds:
+
+1. **AI in a tab.** Junior tech opens Claude or ChatGPT, pastes the problem, gets a
+   wall of prose, parses it into action items in their head, executes, repeats. AI
+   does the diagnostic work. The tech does all the structure-extraction and
+   ticket-note-writing afterward.
+
+2. **Tribal knowledge.** Junior tech pings senior in Slack. Senior tech is
+   interrupted (4+ times/day per the founder's own data). Context handoff is verbal
+   and lossy.
+
+3. **Stale runbooks.** Half-maintained Notion / IT Glue / SharePoint pages that
+   nobody trusts because they're 18 months out of date and don't match the current
+   customer environment.
+
+The cost of these workarounds for the founder personally: ~20 hours per week of
+senior-tech time lost. For a 5-tech MSP, the equivalent is 1 full FTE worth of
+senior-engineer hours leaking into context-switching and tab-hopping.
+
+## Target User & Narrowest Wedge
+
+**Target user:** Senior Systems Engineer at a small-to-mid MSP (5-20 techs). The
+founder is exemplar #1. Buying authority is shared between senior tech (champion)
+and MSP owner (signs the check).
+
+**Narrowest paid wedge:** Escalation Mode. Single sharp feature. When a junior tech
+escalates a ticket they were working in FlowPilot, the senior tech opens the ticket
+and sees the entire structured session state — every step the junior tried, every
+dead end, every command output — instead of starting with "tell me what you tried"
+for five minutes.
+
+Why this is the wedge:
+
+- **Two metrics, not one** (revised after /codex review 2026-04-27):
+  - **Manual baseline** (the Assignment, weeks 0-2): senior tech stopwatches the
+    next 5 escalations. T1 (first diagnostic action) − T0 (open ticket) under
+    today's verbal-handoff workflow. This is the "what you currently lose" number.
+  - **In-product metric** (telemetry, week 3+): time-to-first-action after claim,
+    derived from `ai_session_step` rows where `created_at > SessionHandoff.claimed_at`
+    AND `user_id = SessionHandoff.claimed_by`. This is the "what it is now with
+    structured handoff" number.
+  - **The savings claim** = manual baseline − in-product metric. Quote both
+    explicitly in pilot conversations. Do NOT roll the in-product number alone
+    into "minutes recovered" — that's an apples-to-oranges miscount Codex caught
+    in the cross-model review.
+- **Single-feature demo:** a 2-minute Loom shows the magic moment — junior hits
+  escalate, senior window opens with full structured context. No theory required.
+- **Cross-buyer story:** sells to senior tech (less interruption) AND owner (junior
+  techs resolve faster, take more accounts).
+- **Hours-saved math is simple:** 4-5 minutes per escalation × 15-30 escalations
+  per week per senior tech = 1-2 hours/week recovered per senior. At $80-150/hr
+  fully-loaded senior tech cost, the tool pays for itself with one customer.
+
+## Constraints
+
+- **One-founder shop.** Cannot run three concurrent product narratives. Sequence
+  matters more than scope.
+- **Pre-PMF runway implied.** 4-8 week build cycles before talking to a buyer are
+  expensive. Approach A's 1-2 week timeline is the binding constraint.
+- **Existing architecture is mostly aligned.** FlowPilot, unified_chat_service,
+  FlowProposal, ConnectWise PSA integration — most of the pieces exist. Risk is
+  positioning and UX, not capability.
+- **PSA copilot competition is real.** ConnectWise / Autotask / Halo are racing to
+  ship AI features. The wedge has to be sharp because we lose on distribution.
+
+## Premises
+
+The five load-bearing claims this design rests on, all confirmed in session:
+
+1. **Diagnostic AI is commoditized.** ResolutionFlow does not compete on
+   "AI solves the ticket faster." That race is over. ChatGPT/Claude already won.
+2. **The structuring layer is the wedge.** AI conversational output is too dense
+   and unstructured for active troubleshooting. ResolutionFlow's value is
+   organizing that output into actionable, separable, recorded steps.
+3. **Escalation context is the killer feature.** "Junior hits escalate, senior gets
+   full structured context in 30 seconds instead of 5 minutes" is the sharpest
+   demoable moment in the entire product surface.
+4. **First paying customer is bottom-up, prosumer-flavored.** Senior tech at a
+   small MSP, $20-50/seat/month, monthly billing. Owner-targeted enterprise
+   pricing waits until 5+ paying shops establish baseline ROI numbers.
+5. **Distribution is MSP communities, not paid SaaS ads.** r/msp, MSPGeek, RocketMSP,
+   PSA marketplace listings. The channel matches the buyer.
+
+## Approaches Considered
+
+### Approach A: Escalation Mode first (REDUCED SCOPE per /plan-eng-review)
+
+Lead the GTM with the killer feature. Polish the escalate-with-context handoff:
+junior tech mid-session hits escalate, senior tech window opens with full
+structured session state. 2-min demo Loom. Pilot with **3 MSPs** in the founder's
+network (capped at 3 to preserve build capacity for B). Metric: minutes recovered
+per escalation.
+
+**SCOPE REDUCTION (2026-04-27 eng review):** ~80% of Approach A is already built.
+The original 2-3 week estimate assumed greenfield. Codebase audit confirms:
+
+| What the doc said "build" | What actually exists |
+|---|---|
+| Session-state serialization | `ai_session.escalation_package` (JSONB), `SessionHandoff.snapshot` |
+| Senior-tech inbox | [EscalationQueuePage.tsx](frontend/src/pages/EscalationQueuePage.tsx) + [EscalationQueue.tsx](frontend/src/components/flowpilot/EscalationQueue.tsx) |
+| Claim workflow | [handoff_manager.py:123 claim_session()](backend/app/services/handoff_manager.py#L123) |
+| API surface | [session_handoffs.py](backend/app/api/endpoints/session_handoffs.py) — POST /handoff, /claim, GET queue |
+| AI assessment for senior | `_generate_ai_assessment()` in handoff_manager |
+| PSA round-trip | `escalation_package_markdown`, `escalation_package_external_id` |
+
+**Real engineering scope (~6-9 days):**
+
+1. **Notification dual-path** (4-5 days). `notification_sent` flag is a dead column —
+   never written. Wire two channels in `handoff_manager.create_handoff`:
+   - **Email** (existing `EmailService.send_notification_email`) — handles offline seniors.
+   - **WebSocket / SSE push** to the EscalationQueue for live demo magic moment.
+   - Set `notification_sent=true` after dispatch confirmation.
+   - Graceful degradation: handoff still created if notification raises (regression test required).
+
+2. **Hero metric endpoint** (~2 hours). New `GET /api/v1/analytics/escalation-metrics`,
+   account-scoped, role-gated to `require_engineer_or_admin`. Computes
+   *minutes recovered per escalation* by querying:
+   ```
+   ai_session_step.created_at (first row by senior_tech_user_id where created_at > SessionHandoff.claimed_at)
+   minus
+   SessionHandoff.claimed_at
+   ```
+   Returns a rolling-30-day average per account. No schema change.
+
+3. **UX polish on EscalationQueue + receiving-engineer view** (2-3 days). Confirm the
+   magic-moment screen lands when senior clicks claim. Add an unread indicator on
+   the queue. Wire optimistic insert when SSE event arrives.
+
+4. **Loom + landing page copy** (1-2 days). Non-engineering. Outside this plan's scope
+   but required for the GTM in week 3.
+
+**Test plan:** 100% coverage of new paths — 13 tests including 4 e2e and 1 regression
+(graceful-degradation when notification dispatch raises). Test plan artifact at
+`~/.gstack/projects/chihlasm-resolutionflow/abc-main-eng-review-test-plan-20260427-000000.md`.
+
+**Risk:** Low. Single feature, single metric, architecture-aligned. The dual-path
+notification is the only mildly novel surface; both halves use existing infra.
+
+**Reuses:** `services/handoff_manager.py`, `services/escalation_package_generator.py`,
+`models/session_handoff.py`, `models/ai_session.py`, `services/notification_service.py`,
+`models/notification_log.py`, EmailService, EscalationQueuePage + EscalationQueue.
+
+### UI Specifications (locked by /plan-design-review 2026-04-27)
+
+**Magic-moment screen** (new, after Pick Up click): dedicated handoff-context view that
+loads BEFORE the regular FlowPilot session view, then dissolves on first senior action.
+Four sections, single frame:
+
+1. **Problem summary** (top, 2-3 lines): junior's framing. Bricolage Grotesque h2.
+2. **What's been tried** (left or middle column): structured list of `dead_ends_flagged[]`
+   and `steps_attempted[]` from `escalation_package` JSONB. Card-flat surface, IBM Plex.
+3. **AI assessment** (right column): `ai_assessment_data` rendered as 3 fields —
+   `likely_cause`, `suggested_steps[]`, `confidence`. accent-dim badge for confidence.
+4. **Start here** (primary CTA, electric-blue, ≥44px touch target): opens FlowPilot
+   session at the most-likely-next-step. Senior typing or clicking anywhere triggers
+   200ms fade-out and FlowPilot view fades in. Re-openable via "Show handoff context"
+   ghost button in FlowPilot toolbar.
+
+**Hero metric ("minutes recovered per escalation"):** lives in TWO places:
+- **Queue stat-card** (above EscalationQueue list on /escalations): compact, "X.X hrs
+  saved this month" + "click for details" affordance. Refreshes on queue load.
+- **Dedicated `/analytics/escalations` page** (owner-facing): trend chart (4-week
+  rolling), per-tech breakdown, per-problem-domain segmentation. Engineer-or-admin
+  role-gated.
+
+**Real-time arrival visual** (when WebSocket pushes a new escalation):
+- New card slides in from above the list, 200ms ease-out CSS transition.
+- Browser tab title prefixes with " (1) " / " (N) " when tab is backgrounded; clears
+  on focus.
+- No sound. MUST respect `prefers-reduced-motion: reduce` (slide-in collapses to
+  instant fade-in).
+
+**Unread state:** subtle 6px dot in top-right corner of card for escalations the
+current senior has never opened. Dot fades on first hover or click.
+
+**Race-condition (two seniors click Pick Up simultaneously):** loser sees a toast
+"Already claimed by [name] 2s ago" via existing `@/lib/toast`; the card flashes the
+winner's name in the meta row for 1s, then dissolves from the loser's view via
+optimistic update + WebSocket reconciliation.
+
+**Unread state (Codex correction 2026-04-27):** dot indicator clears on **open,
+claim, or explicit dismiss** — NOT on hover. Hover-to-clear is a bad proxy for
+acknowledgment because incidental mouse movement creates false clears.
+
+**Notification routing (Codex finding 2026-04-27):** v1 fans out the email + push
+to **all engineer-or-admin role users in the same account_id as the SessionHandoff**.
+No on-call/round-robin logic in v1. If pilots ask for routing, capture as v2 TODO.
+The first senior to claim wins; everyone else's notification self-resolves on
+WebSocket reconciliation.
+
+**Notification delivery model (Codex correction 2026-04-27):** drop the
+`notification_sent: bool` flag from v1. Replace with per-channel delivery rows
+in a new `notification_log` table (already exists — reuse, don't add a new model)
+keyed by `(handoff_id, channel, recipient_user_id, status)` where status ∈
+{queued, sent, failed, suppressed}. This makes partial-success and per-channel
+retry visible. If the existing `notification_log` schema doesn't match, defer
+the per-channel persistence to a v2 TODO and v1 logs delivery attempts to the
+existing telemetry stream instead. Do NOT keep the dead boolean.
+
+**"Start here" CTA (Codex correction 2026-04-27):** opens the FlowPilot session
+at the **latest known state** (the AI's most recent agent_message + the current
+pending_task_lane). Surface `ai_assessment_data.suggested_steps[]` as a list of
+chips below the chat input — clicking a chip prefills the input. Do NOT invent a
+"jump to most-likely-next-step" capability that doesn't exist in the session model.
+
+**`/claim` role gate (Codex correction 2026-04-27, IN-SCOPE for v1):** add
+`require_engineer_or_admin` dep on POST `/handoffs/{id}/claim`. Originally
+deferred to TODO during eng review; Codex correctly flagged it as wedge-relevant
+because the race-condition story depends on auth gating. ~30 min change. Removed
+from TODO.md.
+
+**A11y requirements (mandatory before pilot ship):**
+- Keyboard: Tab order through queue cards; Enter on focused card opens it; Pick Up
+  button is a reachable target; Esc closes the handoff-context overlay.
+- ARIA: `role="region"` + `aria-live="polite"` on the queue list (announces arrivals);
+  `aria-label="N escalations awaiting pickup"` on the heading; the slide-in animation
+  must not announce twice (debounce live-region updates).
+- Pick Up button: bump from `py-2` to `py-2.5` to clear the 44px touch-target floor.
+- Color contrast: confidence-badge text on accent-dim background must be ≥4.5:1
+  (verify against DESIGN-SYSTEM.md tokens).
+
+**DS token discipline:** every new piece must use `card-flat`, `accent-dim`/`accent-text`,
+`text-muted-foreground`, `bg-card`/`bg-elevated`, IBM Plex / Bricolage / JetBrains,
+explicit `transition` property lists (never `transition: all`). No glass, no blur,
+no gradient surfaces. Electric-blue accent reserved for interactive elements only.
+
+**Mobile responsive:** deferred to post-pilot TODO. Pre-PMF wedge target is desktop;
+MSP techs work on laptops/desktops in shop environments.
+
+**Deferred to TODO.md (out of scope for v1 wedge):**
+- Peer-tech escalates colleague's session (currently session-owner-only)
+- Role gate on POST /claim (currently any authenticated user in account)
+
+### Approach B: Full Structured Resolution loop (split B1 + B2)
+
+End-to-end demo: tech opens FlowPilot, structure appears in side panel as AI
+responds, ticket notes auto-populate at end, optional runbook capture for reusable
+patterns. Tells the full "senior engineer over your shoulder" story.
+
+**B1 — Side panel + PSA-formatted ticket notes** (ships first):
+- Structured side panel that surfaces parsed AI markers as live actionable steps
+  while the conversation runs.
+- PSA-formatted ticket-notes exporter (ConnectWise first; Autotask/Halo later).
+- Effort: M (~3 weeks).
+
+**B2 — Runbook offer-and-save** (gated on pilot demand):
+- "Save this resolution as a flow?" prompt at session end, with auto-drafted
+  runbook from the structured session state.
+- Effort: S (~1 week). Don't build until at least 2 pilot customers explicitly
+  ask for it.
+
+- **Risk:** Medium. The structured-output panel quality is the whole demo. If it
+  looks dumb, the demo dies.
+- **Reuses:** FlowPilot, unified_chat_service, FlowProposal, ConnectWise PSA
+  integration.
+
+### Approach C: Senior-Tech Time-Saved Counter
+
+Continuous measurement layer underneath A and B. Every session contributes an
+estimated minutes-saved number. Owner-facing dashboard quotes "this month your
+shop saved N hours of senior-tech time." Sells to MSP owner with verifiable ROI.
+
+- **Effort:** S (~1 week + ongoing measurement methodology refinement).
+- **Risk:** Medium-low. Methodology has to be defensible. If numbers look
+  made-up, trust dies fast.
+- **Reuses:** FlowPilot telemetry, session metadata, account-scoped analytics.
+
+## Recommended Approach
+
+**A first (1-2 weeks), then B (3-4 weeks after A ships), with C running underneath
+both as a continuous backdrop.**
+
+Sequence rationale:
+
+- **A is the sharpest possible 2-minute demo.** Single feature, single metric,
+  buyer-verifiable in their own data. Get it in front of 5 MSPs in week 3.
+- **B is the depth play.** Once Approach A has produced first-pilot signal,
+  Approach B's full structured-resolution loop becomes the "what we ship next" that
+  retains pilots and converts them to paid.
+- **C compounds across both.** Every session under A or B contributes to the
+  time-saved counter. By week 6 there are real numbers to put in front of an MSP
+  owner — turning a senior-tech-led pilot into an owner-signed contract.
+
+This sequence is non-negotiable. Building B before A is the classic pre-PMF trap of
+perfecting product before validating GTM. Building C alone is measurement without a
+demo to anchor it.
+
+## Pricing
+
+**Pilot pricing (first 3-5 customers): $39/seat/month, monthly billing,
+month-to-month.** Anchored against IT Glue (~$29/tech), Hudu (~$25/tech),
+Liongard (~$3/endpoint). The premium over IT Glue/Hudu reflects the active-session
+value (vs. their static-runbook value) — 30% above the runbook-only category.
+
+Customer #6+ pricing is an Open Question (revisit after 3 pilots produce real
+hours-saved data; price up if the per-seat ROI is over $200/seat/mo).
+
+## Open Questions
+
+1. **Free-tier shape.** Should the time-saved counter be free forever as a
+   distribution lever, with paid for the structuring + escalation? Land-and-expand
+   pattern. Decide after 3 pilot conversions.
+2. **PSA-marketplace timing.** ConnectWise Marketplace listing requires partnership
+   onboarding (~6-week cycle). Submit application week 5; expect listing live by
+   week 11. Don't gate launch on it.
+3. **Customer #6+ pricing.** Revisit after 3 pilot customers produce verifiable
+   hours-saved numbers.
+
+## Deferred (YAGNI until 10 paying customers)
+
+- HIPAA / SOC2 audit positioning. Pre-PMF is too early; revisit when a regulated-
+  vertical MSP asks for it explicitly.
+- Multi-PSA depth (Autotask, Halo). ConnectWise alone covers ~40% of the SMB MSP
+  market and is sufficient for first 5-10 customers.
+- Cross-tenant pattern detection. The data-flywheel-across-shops play is at least
+  6 months out; building it before single-shop ROI is proven is premature.
+
+## Success Criteria (revised for realism)
+
+- **Week 3:** Approach A shipped. 3 MSPs in active free pilot (cap at 3 to
+  preserve B1 build capacity).
+- **Weeks 3-6:** Pilot management dominates. B1 build is paused; founder runs
+  pilot calls, captures bug reports, iterates UX. Stripe seat-based billing is
+  set up in week 5.
+- **Week 6:** First verbal commit from a pilot customer. Verified
+  minutes-recovered-per-escalation number from at least 2 pilots.
+- **Week 8:** First paid customer (procurement cycles run 4-6 weeks even at small
+  MSPs; 2 weeks from verbal commit to signed contract is realistic). Time-saved
+  counter (Approach C) producing dashboard-quality data.
+- **Week 11:** B1 (side panel + PSA notes) shipped. 3-5 paying customers. First
+  MSP-owner-led conversation. ConnectWise Marketplace listing live.
+- **Quarter end:** $5K MRR or 10 paying customers, whichever comes first. Loom
+  demos posted publicly to r/msp and MSPGeek.
+
+## Distribution Plan (week-by-week cadence)
+
+- **Week 3:** Escalation Mode demo Loom posted. r/msp launch post.
+- **Week 4:** MSPGeek Discord AMA scheduled. RocketMSP newsletter pitch sent.
+- **Week 5:** ConnectWise Marketplace listing application submitted. Stripe
+  billing live for paid conversion.
+- **Week 6:** First "guest on Inside MSP podcast" outreach. Second r/msp post
+  (case study from a pilot, anonymized).
+- **Week 7-8:** Pilot conversion calls. First paying customer.
+- **Week 9-11:** B1 ships. Owner-targeted demo Loom. Second podcast outreach.
+
+**Founder-led pilot:** The first 3-5 customers come from the founder's existing
+MSP network. Treat them as design partners; expect to ship feature requests
+weekly during pilot. Cap at 3 active pilots until B1 ships.
+
+**Tech audience channels:** r/msp, r/sysadmin, MSPGeek Discord, RocketMSP
+newsletter, Inside MSP podcast.
+**Owner audience channels:** ConnectWise Marketplace, MSP-focused Substacks,
+RIA Vendor Roundup.
+
+CI/CD: existing Railway auto-deploy via GitHub mirror. No new pipeline needed.
+
+## Dependencies
+
+- **Session-state serialization (Approach A blocker).** Schema design + migration
+  is the longest-lead engineering task. 3-5 days budget. Do this first.
+- **Stripe seat-based billing (week 5 task).** No billing infrastructure exists
+  today. ~3-5 days of work for monthly subscriptions + invoice flow. Block on
+  this before week-8 first-paid milestone.
+- **ConnectWise PSA integration depth.** Sufficient for ticket-notes auto-export
+  (Approach B1). Autotask and Halo wait until first 5 paying ConnectWise
+  customers.
+- **Authentication.** Existing JWT + role hierarchy is sufficient for senior-tech
+  inbox view; no new auth work needed.
+
+## Risks and Kill-Switch
+
+- **Risk: Session-state serialization design churn.** If the schema needs to
+  change after pilot feedback, every saved session has to migrate. Mitigation:
+  keep schema versioned and forward-compatible from day 1.
+- **Risk: Pilot-to-paid conversion slower than 4-6 weeks.** MSP procurement is
+  notoriously slow. Mitigation: get verbal commits in writing; price as
+  month-to-month with no annual contract to lower the buying friction.
+- **Risk: ConnectWise ships an equivalent feature in their 2026.x release.**
+  Mitigation: lead the marketing on "we're independent of your PSA" — works with
+  any PSA, not just ConnectWise. The founder's PSA-agnostic FlowPilot is an
+  asset here.
+- **Kill-switch criterion:** if 0 of 3 pilots produce a verifiable
+  hours-saved-per-week number above 1.0 by week 8, **revisit the wedge**. The
+  product may need to pivot to deterministic-ops territory (Read 1 from the
+  session) or be repositioned. Don't sink another quarter into the current GTM
+  story without this number.
+
+## The Assignment
+
+**This week, before any code:**
+
+Time-track the next 5 escalations in your shop manually. For each, capture:
+1. Time the senior tech opens the ticket
+2. Time the senior tech takes their first diagnostic action (not counting the
+   verbal "tell me what you tried" warm-up)
+3. The delta — that's the wasted time per escalation today
+
+Average those 5 numbers. **That's the hero stat in your first sales conversation:**
+"Senior techs at our shop wasted N minutes per escalation just getting up to
+speed. We built the thing that takes that to zero."
+
+Don't try to pull this from telemetry — the doc itself notes that retrieval/re-use
+data isn't queryable yet. Manual stopwatch on the next 5 escalations is the
+fastest path to a defensible number.
+
+This is the assignment because it forces the GTM story into the same time-zone as
+the build, and it's a one-day effort that compounds for every conversation
+afterward.
+
+## What I noticed about how you think
+
+- You contradicted my framing twice in the same session and the second
+  contradiction was sharper than the first. Most founders agree with the
+  diagnostic and walk out with a polished version of what they came in with. You
+  said "I'm just questioning if flows are even the way to go" — and that
+  sentence reset the entire wedge. That's craft.
+
+- "The senior engineer looking over your shoulder" came out of you spontaneously,
+  not as a prepared pitch. That's the line. Use it. It survives because it's
+  emotional truth (every junior tech has had this, every senior tech has been
+  this), not constructed marketing copy.
+
+- You're solving your own problem with your own time. 20 hrs/week isn't a
+  hypothetical user pain — it's your Tuesday. Founders who solve their own pain
+  ship sharper products because the feedback loop is instant.
+
+- The escalation feature emerged from your description, not mine. I was busy
+  cataloging documentation pains. You said "junior to senior escalation? no
+  worries there either" almost as an afterthought. That afterthought is the wedge.
+  Pay attention to which features you describe casually versus which you push hard
+  on — the casual ones are sometimes where the truth lives.
+
+## GSTACK REVIEW REPORT
+
+| Review | Trigger | Why | Runs | Status | Findings |
+|--------|---------|-----|------|--------|----------|
+| CEO Review | `/plan-ceo-review` | Scope & strategy | 0 | — | not run |
+| Codex Review | `/codex review` | Independent 2nd opinion | 1 | INFO | 12 findings, 6 applied, 1 partial, 5 rejected |
+| Eng Review | `/plan-eng-review` | Architecture & tests (required) | 1 | CLEAR (PLAN) | 2 issues, 0 critical gaps, scope reduced |
+| Design Review | `/plan-design-review` | UI/UX gaps | 1 | CLEAR (FULL) | score 6/10 → 9/10, 8 decisions |
+| DX Review | `/plan-devex-review` | Developer experience gaps | 0 | — | not run |
+
+- **CODEX:** 12 findings reviewed. Applied: 2-metric framing (#2), notification routing spec (#3), per-channel delivery model (#4), unread-state fix (#11), Start-here CTA reframe (#9), claim role gate moved in-scope (#8). Rejected: full scope reduction to PSA-brief-only (#6/7/12 — user kept queue UI as demo hero). Partial: scope concern (#5) acknowledged in eng review's email-first/polling-fallback. Misread: #1, #10.
+- **CROSS-MODEL:** Claude (eng + design reviews) and Codex agree on 6/12 findings. The major disagreement was scope — Codex argued for cutting the queue UI, user rejected. Both agree on metric definition, notification routing, claim auth gating.
+- **UNRESOLVED:** 0
+- **VERDICT:** ENG + DESIGN CLEARED, CODEX REVIEWED — ready to implement.

docs/plans/2026-04-27-escalation-mode-wedge-test-plan.md

@@ -0,0 +1,33 @@
+# Test Plan
+Generated by /plan-eng-review on 2026-04-27
+Branch: main
+Repo: chihlasm/resolutionflow
+
+## Affected Pages/Routes
+
+- `/escalations` ([EscalationQueuePage.tsx](frontend/src/pages/EscalationQueuePage.tsx)) — senior-tech inbox view; verify queue list, real-time arrival, click-through
+- `/pilot/:session_id` (FlowPilotSessionPage) — verify post-claim load shows full escalation context (snapshot, ai_assessment, escalation_package)
+- `GET /api/v1/analytics/escalation-metrics` (NEW) — verify hero metric calculation, account-scoping, role gate
+
+## Key Interactions to Verify
+
+- Junior tech clicks **Escalate** in active FlowPilot session → handoff is created → notification fires → senior sees escalation in queue within 30 seconds
+- Senior tech clicks **Claim** in queue → session reactivates → senior is redirected into FlowPilot session view → ai_assessment + snapshot are visible
+- Senior types first message in chat after claim → metric query starts attributing time-to-first-action
+- MSP owner opens analytics page → "minutes recovered per escalation" widget shows current month's rolling average
+
+## Edge Cases
+
+- **Two seniors race to claim** the same handoff → one wins, the other gets a "Already claimed by [name]" message
+- **Senior is offline** when escalation fires → email arrives via existing `EmailService.send_notification_email`
+- **WebSocket disconnects mid-session** → frontend reconnects; missed events backfilled by re-fetching the queue
+- **Notification dispatch raises** (SMTP down, WebSocket fanout fails) → handoff is still created (graceful degradation)
+- **Senior takes non-chat action first** (e.g., posts directly to PSA) → metric falls back to PSA writeback timestamp or remains null; doc the chosen behavior
+- **Account-scoped multi-tenancy** → senior at MSP A cannot see escalations from MSP B (Phase 4 RLS)
+- **Role gate on metric endpoint** → only `engineer_or_admin` can hit `/escalation-metrics`
+
+## Critical Paths
+
+1. **Magic-moment demo flow** (the entire Loom): junior escalate → senior notification → senior claim → session view → first action recorded → metric updates
+2. **Email fallback** when senior is offline — must not silently drop
+3. **Regression: handoff creation succeeds even if notification dispatch raises** — graceful degradation is mandatory

docs/plans/2026-05-01-issue-cleanup-plan.md

@@ -0,0 +1,81 @@
+# Issue Cleanup Plan - 2026-05-01
+
+## Tracker Hygiene
+
+These are safe tracker updates before any feature work:
+
+1. Close Gitea #127 (`feat: show AI content scope indicator`) unless an always-visible badge is still desired.
+   - Current code already has IT/MSP scope copy in the assistant empty state.
+   - `ASSISTANT_SYSTEM_PROMPT` also has an off-domain redirect boundary.
+2. Rewrite Gitea #66 (`Tree Templates + Import/Export`) to the remaining scope only.
+   - `.rfflow` export/import is implemented in `tree_transfer.py` and exposed in the library UI.
+   - Remaining work: curated packs, authenticated one-click install from gallery, template versioning, marketplace/community path.
+3. Close or archive open PR #124 (`feat/cockpit-harness`).
+   - It is unmergeable against current `main` and overlaps newer `/pilot` work.
+4. Keep Gitea #58, #60, #128, #129, #130 open.
+   - They still describe real product gaps.
+
+## Recommended Order
+
+### 1. Low-Risk Maintenance
+
+- Status: started 2026-05-01.
+- Frontend lint is clean after removing stale disable comments and tightening hook dependencies.
+- Added `data-testid` selectors for e2e-critical session history and FlowPilot command-palette controls.
+- Added `AssistantChatPage` observability for unexpected `currentChatRef` guard mismatches so stale async discards are visible in the console.
+
+Why first: these reduce future regression cost and are small, well-bounded changes.
+
+### 2. Pilot UX Friction
+
+- Status: started 2026-05-01.
+- #130: Added diagnostic command help affordances in `TaskLane` action cards. Each active diagnostic card can explain what it checks, what to look for, and when to use it.
+- #128: Keep the existing responsive drawer behavior for now. `TaskLane` already uses a side panel on wide screens and a bottom drawer below the desktop breakpoint; do not add a top/side preference unless pilot feedback shows the current responsive layout is blocking workflow.
+- EscalationQueue mobile design stays deferred until a customer asks for it.
+
+Why second: this improves the current FlowPilot wedge without changing core data models.
+
+Validation run:
+
+- `docker exec -w /app resolutionflow_frontend npm run lint`
+- `docker exec -w /app resolutionflow_frontend npx tsc -b`
+- `docker exec -w /app resolutionflow_frontend npm run build`
+
+### 3. Workflow Quality Signals
+
+- #58: Add structured "step is wrong" flags separate from thumbs-up/down helpfulness.
+- Existing `StepFeedback` is not enough; it only records helpful/unhelpful and cannot capture incorrect/outdated/unclear/missing-info reasons.
+
+Why third: useful, but needs schema/API/UI/admin surfaces.
+
+### 4. Client Intelligence
+
+- #60: Recurring issue detection.
+- Start with a read-only banner using existing `sessions.client_name + tree_id` filters.
+- Add same-resolution detection only after confirming the available session outcome/node data is reliable enough.
+
+Why fourth: high value, but it touches session-start and close-out flows and needs careful false-positive handling.
+
+### 5. Documentation Structure
+
+- #129: Hierarchical guide navigation.
+- Current `/guides` route is a card grid plus detail pages with sections and breadcrumbs, but not a collapsible guide tree.
+
+Why fifth: valid UX request, but less urgent than pilot workflow gaps.
+
+## Gitea Actions Needed
+
+The current environment does not have a Gitea token configured, so API writes fail with `401 token is required`. Once authenticated:
+
+```bash
+curl -X PATCH \
+  https://gitea.resolutionflow.com/api/v1/repos/chihlasm/resolutionflow/issues/127 \
+  -H "Authorization: token $GITEA_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"state":"closed"}'
+```
+
+For #66, prefer editing the title/body instead of closing it:
+
+- Title: `feat: curated template packs and one-click install`
+- Body: remove completed `.rfflow` export/import acceptance criteria and keep pack/install/versioning work.

docs/superpowers/plans/2026-05-06-self-serve-signup-phase-2-frontend-cutover.md

@@ -0,0 +1,968 @@
+# Self-Serve Signup & Onboarding — Phase 2: Frontend + Cutover
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task.
+>
+> **Granularity note:** Unlike Phase 1, this plan defines *contracts and acceptance criteria* — not every component detail. Implementers exercise judgment on internal structure (hooks vs. props, file splits, CSS organization) as long as the contracts hold and integration tests pass. Steps use checkbox (`- [ ]`) syntax for tracking; each task is one mergeable PR.
+
+**Goal:** Layer the user-facing self-serve flow on top of the Phase 1 backend foundation — pricing page, OAuth buttons + register redesign, welcome wizard, dashboard redesign with trial pill + next-step card + checklist, accept-invite page, sales contact form, billing portal — gated behind `SELF_SERVE_ENABLED` and `VITE_SELF_SERVE_ENABLED` until cutover.
+
+**Architecture:** Frontend reads billing state from a new `useBillingStore` Zustand store fed by `GET /billing/state`. New routes layer on the existing React Router v7 + lazyWithRetry pattern. Wizard state is server-persisted via `PATCH /users/me/onboarding-step`. Authenticated routes mount under existing `AppLayout`; public routes (pricing, contact-sales, accept-invite, verify-email) are top-level. Cutover is two flag flips: backend `SELF_SERVE_ENABLED=true`, frontend `VITE_SELF_SERVE_ENABLED=true`.
+
+**Tech Stack:** React 19 + Vite + TypeScript, Tailwind v4 (CSS-only config), Zustand (immer + zundo), React Router v7, Axios, Lucide. Backend additions: a few small endpoints (Phase 1 left them out) — see Phase I.
+
+**Spec reference:** `docs/superpowers/specs/2026-05-05-self-serve-signup-onboarding-design.md` (commit `bbb01ef`).
+**Phase 1 reference:** `docs/superpowers/plans/2026-05-06-self-serve-signup-phase-1-backend.md`.
+
+---
+
+## Phase Sequencing
+
+Each phase ends in a mergeable PR. Frontend gates everything behind `VITE_SELF_SERVE_ENABLED` so the new surfaces stay invisible to public users until Phase O cutover.
+
+| Phase | Tasks | Outcome |
+|---|---|---|
+| I | 27–31 | Backend endpoints Phase 1 deferred + `SELF_SERVE_ENABLED` flag + `/admin/plan-limits` extension |
+| J | 32–34 | Frontend billing foundation: `useBillingStore`, hooks, gating components — proven against Phase 1 backend |
+| K | 35–37 | Auth surfaces: register redesign with OAuth buttons, accept-invite page, email-verification surfaces |
+| L | 38–39 | Welcome wizard — 3 steps with persistence |
+| M | 40–41 | Dashboard redesign — trial pill, next-step card, checklist redesign |
+| N | 42–44 | Public surfaces: pricing page, contact-sales form, landing-page CTA, beta-signup 307 |
+| O | 45–47 | Cutover: Stripe live-mode setup, internal validation, feature-flag flip |
+
+---
+
+## Phase I — Backend endpoints + admin extension + feature flag
+
+### Task 27: BillingService.open_customer_portal + GET /billing/portal-session
+
+**Outcome:** Authed users can request a Stripe-hosted Customer Portal URL for card updates and cancellation.
+
+**Contract:**
+
+```
+GET /api/v1/billing/portal-session
+  → 200 { url: string }
+  → 503 when STRIPE_SECRET_KEY unset
+  → 400 when account has no stripe_customer_id (must complete checkout first)
+```
+
+`BillingService.open_customer_portal(account)` creates a `stripe.billing_portal.Session` with `return_url=$FRONTEND_URL/account/billing` and returns the session URL.
+
+**Acceptance criteria:**
+
+- [ ] Endpoint mounted at `/billing/portal-session` and is in the `_SUBSCRIPTION_GUARD_ALLOWLIST` and `_EMAIL_VERIFICATION_ALLOWLIST` (so it works for canceled / unverified-past-grace users who need to update billing).
+- [ ] Returns 400 with `{"error": "no_stripe_customer"}` when `account.stripe_customer_id is None`.
+- [ ] Stripe call mocked via `respx`; happy-path test asserts shape `{url: ...}`.
+
+**Integration test added:**
+
+- `test_billing_portal_returns_url_for_account_with_stripe_customer`
+
+**Commit:** `feat(billing): add BillingService.open_customer_portal + GET endpoint`
+
+---
+
+### Task 28: PATCH /users/me/onboarding-step
+
+**Outcome:** Welcome wizard can persist Step 1/2/3 state to the server.
+
+**Contract:**
+
+```
+PATCH /api/v1/users/me/onboarding-step
+  body: {
+    step: 1 | 2 | 3,
+    action: "complete" | "skip",
+    data?: {
+      // step 1
+      company_name?: string,
+      team_size_bucket?: "1-2"|"3-5"|"6-10"|"11-25"|"26+",
+      role_at_signup?: "owner"|"lead_tech"|"tech"|"other",
+      // step 2
+      primary_psa?: "connectwise"|"autotask"|"halopsa"|"none",
+      // step 3 has no data — invitations posted separately to /accounts/me/invites/bulk
+    },
+  }
+  → 200 { onboarding_step_completed: int, onboarding_dismissed: false }
+```
+
+Writes:
+- step=1 + action=complete → `accounts.name`, `accounts.team_size_bucket`, `users.role_at_signup`, `users.onboarding_step_completed=1`
+- step=1 + action=skip → `users.onboarding_step_completed=1` only (no field writes)
+- step=2 → `accounts.primary_psa` (only on complete) + `users.onboarding_step_completed=2`
+- step=3 → `users.onboarding_step_completed=3` (the actual invites POST is separate)
+
+Validates: `step` cannot decrease; `action="skip"` ignores the `data` payload.
+
+**Endpoint also exposes a sibling:** `POST /users/me/onboarding-dismiss-rest` → sets `users.onboarding_dismissed=TRUE`. Used by "Skip the rest" button.
+
+**Acceptance criteria:**
+
+- [ ] In `_EMAIL_VERIFICATION_ALLOWLIST` (so users can move through the wizard before verifying email).
+- [ ] In `_SUBSCRIPTION_GUARD_ALLOWLIST` (wizard runs during the trial; never gated).
+- [ ] Refusing to decrease `step` is enforced (a step=2 PATCH followed by step=1 returns 400).
+- [ ] Tests cover: complete with data writes fields; skip without data only advances step; idempotent re-PATCH of same step.
+
+**Integration tests added:**
+
+- `test_onboarding_step1_complete_writes_account_name_and_team_size_and_role`
+- `test_onboarding_step2_skip_advances_without_psa`
+- `test_onboarding_step_cannot_decrease`
+- `test_onboarding_dismiss_rest_sets_flag`
+
+**Commit:** `feat(onboarding): add PATCH /users/me/onboarding-step + dismiss-rest`
+
+---
+
+### Task 29: POST /sales-leads endpoint
+
+**Outcome:** Public Talk-to-sales form has somewhere to post.
+
+**Contract:**
+
+```
+POST /api/v1/sales-leads
+  body: {
+    email: string,
+    name: string,
+    company: string,
+    team_size?: string,
+    message?: string,
+    source: "pricing_page" | "register_footer" | "landing_page",
+    posthog_distinct_id?: string,
+  }
+  → 201 { id: uuid, status: "received" }
+```
+
+Public — no auth required. Rate-limit: max 5 submissions per IP per hour (use existing `core.rate_limit`).
+
+Side effects:
+1. Insert `sales_leads` row.
+2. Fire-and-forget `EmailService.send_sales_lead_notification` to `settings.SALES_LEAD_RECIPIENT_EMAIL` (new env var, default `sales@resolutionflow.com`).
+3. Emit PostHog server-side event `talk_to_sales_form_submitted` with `source` property.
+
+**Acceptance criteria:**
+
+- [ ] Anti-spam: rate-limited per IP.
+- [ ] Email send failure doesn't fail the request (logged warning).
+- [ ] Sales-lead recipient email is configurable; defaults to a placeholder until cutover.
+
+**Integration tests:**
+
+- `test_sales_lead_creates_row_and_sends_notification_email`
+- `test_sales_lead_rate_limited_after_5_per_hour`
+
+**Commit:** `feat(sales): add POST /sales-leads public endpoint`
+
+---
+
+### Task 30: Extend /admin/plan-limits to surface plan_billing fields
+
+**Outcome:** Super-admins can manage plan_billing (Stripe IDs, display names, prices, public/archived flags) via the same admin page they already use.
+
+**Contract change:**
+
+```
+GET /api/v1/admin/plan-limits → list[PlanLimitWithBillingResponse]
+
+PlanLimitWithBillingResponse extends PlanLimitResponse with:
+  display_name?: string
+  description?: string
+  monthly_price_cents?: int | null
+  annual_price_cents?: int | null
+  stripe_product_id?: string | null
+  stripe_monthly_price_id?: string | null
+  stripe_annual_price_id?: string | null
+  is_public?: bool
+  is_archived?: bool
+  sort_order?: int
+
+PUT /api/v1/admin/plan-limits accepts the same fields; updates plan_billing
+in the same transaction. If a plan_billing row doesn't exist for the plan,
+PUT creates it.
+```
+
+**Acceptance criteria:**
+
+- [ ] Single PUT round-trips both `plan_limits` and `plan_billing` in one transaction.
+- [ ] Cache invalidation: `app.state.billing_cache` flushed for all accounts on the affected plan.
+- [ ] No new admin page in v1 — existing `/admin/plan-limits` UI just gets new form fields.
+
+**Integration tests:**
+
+- `test_admin_plan_limits_get_includes_plan_billing_fields_when_present`
+- `test_admin_plan_limits_put_creates_plan_billing_row`
+- `test_admin_plan_limits_put_invalidates_billing_cache`
+
+**Commit:** `feat(admin): extend /admin/plan-limits to manage plan_billing fields`
+
+---
+
+### Task 31: Wire SELF_SERVE_ENABLED feature flag
+
+**Outcome:** A single flag controls whether the new public-facing self-serve flow is exposed.
+
+**Contract:**
+
+Backend:
+- `settings.SELF_SERVE_ENABLED: bool = False` (already added in Phase 1 Task 14).
+- New endpoint `GET /api/v1/config/public` (no auth) returns `{self_serve_enabled: bool, oauth_providers: ["google", "microsoft"] | []}` — frontend reads this once at load.
+
+Frontend:
+- `VITE_SELF_SERVE_ENABLED` env var (build-time bake-in per Lesson 60).
+- New `useAppConfig` hook: prefers backend `/config/public` response, falls back to `VITE_SELF_SERVE_ENABLED` for build-time gating.
+- Public routes (`/pricing`, `/contact-sales`, `/accept-invite`, OAuth callbacks) return 404 from the frontend router when `self_serve_enabled === false`.
+- Register page hides OAuth buttons + invite-code-removed copy when flag is off (preserves the existing invite-code-required register flow).
+
+**Acceptance criteria:**
+
+- [ ] Flag is OFF by default in all envs except where explicitly enabled.
+- [ ] When OFF: existing `/auth/register` invite-code flow still works exactly as today.
+- [ ] When ON: new flows are reachable; invite-code requirement is removed (the field still exists in the schema for backward-compat but the gate-check accepts NULL).
+
+**Integration tests:**
+
+- `test_get_config_public_returns_self_serve_flag`
+- `test_register_invite_code_required_when_self_serve_disabled` (regression)
+- `test_register_invite_code_optional_when_self_serve_enabled`
+
+**Commit:** `feat(config): add SELF_SERVE_ENABLED flag + GET /config/public`
+
+---
+
+## Phase J — Frontend billing foundation
+
+### Task 32: useBillingStore Zustand store + GET /billing/state integration
+
+**Outcome:** Frontend has a single source of truth for subscription / plan / feature state.
+
+**Contract — store shape:**
+
+```typescript
+// frontend/src/store/billingStore.ts
+interface BillingState {
+  subscription: {
+    status: 'trialing' | 'active' | 'past_due' | 'canceled' | 'incomplete' | 'complimentary'
+    plan: string
+    current_period_start: string | null  // ISO
+    current_period_end: string | null    // ISO
+    cancel_at_period_end: boolean
+    seat_limit: number | null
+    has_pro_entitlement: boolean
+    is_paid: boolean
+  } | null
+  planBilling: {
+    display_name: string
+    description: string | null
+    monthly_price_cents: number | null
+    annual_price_cents: number | null
+  } | null
+  planLimits: Record<string, unknown>
+  enabledFeatures: Record<string, boolean>
+  isLoading: boolean
+  error: string | null
+}
+
+interface BillingStore extends BillingState {
+  fetch: () => Promise<void>
+  refetch: () => Promise<void>
+  reset: () => void
+}
+```
+
+**Behavior:**
+
+- Auto-fetches on auth-store login (subscribe to `authStore`).
+- Auto-resets on logout.
+- Polls every 60s while the dashboard is mounted (simple `useInterval` in a top-level component is fine — no SSE for v1).
+- `refetch()` is exposed for explicit refresh after Stripe Checkout success-redirect.
+
+**Acceptance criteria:**
+
+- [ ] Initial state is null/empty; populates after first successful fetch.
+- [ ] 401 from `/billing/state` triggers logout via existing axios interceptor (no special handling needed).
+- [ ] Polling disabled when no user is logged in.
+
+**Integration tests (Vitest):**
+
+- `useBillingStore fetches on login and populates subscription`
+- `useBillingStore resets on logout`
+- `useBillingStore refetch overwrites stale data`
+
+**Commit:** `feat(billing): add useBillingStore and /billing/state integration`
+
+---
+
+### Task 33: useFeature, useFeatureLimit, useTrialBanner hooks
+
+**Outcome:** Components can ask "is this feature on?" / "how many sessions left?" / "what stage is the trial in?" without re-implementing the read.
+
+**Contract — hook signatures:**
+
+```typescript
+// useFeature: enabled boolean for a feature key
+function useFeature(flagKey: string): boolean
+
+// useFeatureLimit: progress against a quantitative limit
+function useFeatureLimit(field: keyof PlanLimits): {
+  used: number       // from /api/v1/usage/{field} (lazy fetch, cached 60s)
+  limit: number | null
+  percentage: number | null  // null when limit is null (unlimited)
+  isAtLimit: boolean
+  isLoading: boolean
+}
+
+// useTrialBanner: derives stage from subscription state
+function useTrialBanner(): {
+  stage: 'pristine' | 'warning' | 'urgent' | 'expired' | 'complimentary' | 'paid' | 'past_due' | 'canceled' | null
+  daysRemaining: number | null
+}
+```
+
+**Stage derivation:**
+- `subscription.status === 'complimentary'` → `complimentary`
+- `subscription.status === 'active'` → `paid`
+- `subscription.status === 'past_due'` → `past_due`
+- `subscription.status === 'canceled'` → `canceled`
+- `subscription.status === 'trialing'` AND `current_period_end > now()` → `pristine` (>3 days), `warning` (1–3), `urgent` (<1)
+- `subscription.status === 'trialing'` AND `current_period_end <= now()` → `expired`
+
+**Acceptance criteria:**
+
+- [ ] `useFeatureLimit` does NOT block render — returns `isLoading=true` until usage data arrives.
+- [ ] `useTrialBanner` returns `null` when subscription is null (no flicker on initial load).
+- [ ] All three hooks subscribe to `useBillingStore` such that updates propagate without manual refetch.
+
+**Integration tests (Vitest):**
+
+- `useFeature returns false when flag absent`
+- `useFeatureLimit transitions isLoading → loaded`
+- `useTrialBanner stage matches subscription state matrix`
+
+**Commit:** `feat(billing): add useFeature, useFeatureLimit, useTrialBanner hooks`
+
+---
+
+### Task 34: FeatureGate, UpgradePrompt, EmailVerificationGate components
+
+**Outcome:** Three drop-in components that handle the most common gating patterns. Component implementation details (props, layout, Tailwind classes) are at implementer's discretion as long as the API holds.
+
+**Contracts:**
+
+```tsx
+// FeatureGate: render children if feature enabled, else fallback (default <UpgradePrompt />)
+<FeatureGate feature="psa_integration" fallback={<UpgradePrompt feature="psa_integration" />}>
+  <PsaConfigPanel />
+</FeatureGate>
+
+// UpgradePrompt: standardized "this feature is on Pro" affordance with CTA
+<UpgradePrompt feature="psa_integration" />  // resolves display name + plan name internally
+
+// EmailVerificationGate: wraps protected content; renders <EmailVerificationWall /> past grace
+<EmailVerificationGate>
+  <DashboardContent />
+</EmailVerificationGate>
+```
+
+**Behavior:**
+
+- `<FeatureGate>` reads from `useFeature(feature)`. Server-side check via `require_feature` is the security boundary; this is UX.
+- `<UpgradePrompt>` CTA links to `/account/billing/select-plan`.
+- `<EmailVerificationGate>` reads `users.email_verified_at` + `users.created_at` from `authStore.user`. Day 1–6 unverified renders children (banner shown elsewhere). Day 7+ unverified renders `<EmailVerificationWall>`.
+
+**Acceptance criteria:**
+
+- [ ] All three components are exported from `frontend/src/components/common/`.
+- [ ] No CSS-in-JS — Tailwind classes per existing pattern.
+- [ ] Lock icon + greyed style for `<UpgradePrompt>` matches the design system tokens (no `bg-accent` for non-interactive elements per design lessons).
+
+**Integration tests (Vitest + Playwright):**
+
+- `FeatureGate renders children when flag enabled, fallback when disabled` (Vitest)
+- `UpgradePrompt CTA navigates to /account/billing/select-plan` (Vitest)
+- `EmailVerificationGate renders wall on day 8 unverified user` (Vitest, mocked authStore)
+
+**Commit:** `feat(billing): add FeatureGate, UpgradePrompt, EmailVerificationGate components`
+
+---
+
+## Phase K — Auth surfaces
+
+### Task 35: Register page redesign with OAuth buttons + invite-code-optional
+
+**Outcome:** New register flow supports email+password OR Google OR Microsoft, with promo code field collapsed (deferred per spec) and the legacy invite-code field invisible when `SELF_SERVE_ENABLED`.
+
+**Contract:**
+
+Frontend route stays `/register`. Component lives at `frontend/src/pages/RegisterPage.tsx` (modified, not replaced).
+
+Top-of-page CTAs:
+- **"Continue with Google"** button → opens OAuth window → on callback, POSTs `code` to `POST /api/v1/auth/google/callback` → stores tokens via existing auth-store login flow → redirects to `/welcome` (new user) or `/` (returning).
+- **"Continue with Microsoft"** button → same shape against `/auth/microsoft/callback`.
+- **"or sign up with email"** divider, then existing email + password form.
+
+Removed/conditional:
+- **Invite-code field** — hidden when `useAppConfig().self_serve_enabled === true`. When the flag is off, the existing required-invite-code flow runs unchanged.
+- **Promo-code field** — not in v1 (deferred per spec). UI should NOT include it.
+
+`/register?plan=pro` query param is captured into `localStorage` (`rf-intended-plan`) so `BillingService.start_trial` (already runs on Pro by default) can later be enriched OR the in-app picker can preselect.
+
+**Acceptance criteria:**
+
+- [ ] Email+password register call still works; auto-sends verification email per Phase 1 Task 20.
+- [ ] OAuth callback creates User + Account + Subscription per Phase 1 Task 17/18; lands on `/welcome`.
+- [ ] When self-serve disabled: invite-code flow visible, OAuth buttons hidden.
+- [ ] When self-serve enabled: invite-code field hidden, OAuth buttons visible.
+- [ ] Existing test users (`engineer@resolutionflow.example.com` etc.) can still log in via `/login` unchanged.
+
+**Integration tests (Playwright):**
+
+- `register email+password → verification email queued → land on /welcome`
+- `register via Google OAuth (mocked provider) → land on /welcome`
+- `register page hides OAuth + shows invite-code field when self_serve_enabled is false`
+
+**Commit:** `feat(auth): redesign /register with OAuth buttons; hide invite-code under flag`
+
+---
+
+### Task 36: AcceptInvitePage at /accept-invite?code=...
+
+**Outcome:** Invitee from email can join an existing account with set-password OR Google OR Microsoft.
+
+**Contract:**
+
+New top-level route `/accept-invite?code=<32-char-code>`. Component at `frontend/src/pages/AcceptInvitePage.tsx`.
+
+Flow:
+1. On mount, `GET /api/v1/accounts/invites/{code}/lookup` (NEW endpoint — see acceptance criteria) returns `{account_name, inviter_name, invited_email, role}` or 404/410 (expired/revoked/used).
+2. Render: "Join {account_name} on ResolutionFlow" + email locked to `invited_email` + three sign-in options (set password, Google, Microsoft).
+3. On submit, POST to existing `/auth/register` with `account_invite_code` and the email matching `invited_email` (per Phase 1 Task 20 enforcement).
+4. OAuth path: launch provider with state including the invite code; callback POSTs `{code, account_invite_code, invited_email}` to handle linking.
+5. Success → land on `/?welcome=teammate` (suppresses welcome wizard for invitees per spec).
+
+**Backend addition needed (small):**
+
+```
+GET /api/v1/accounts/invites/{code}/lookup
+  → 200 {account_name, inviter_name, invited_email, role}
+  → 404 invite_invalid_or_expired_or_revoked
+```
+
+This is a public endpoint (no auth) reading account-scoped data, so uses `_admin_session_factory()` per the Phase 4 RLS pattern.
+
+**Acceptance criteria:**
+
+- [ ] Invalid/expired/revoked codes show a clear "ask {inviter} to resend" message with a link to email the inviter (via `mailto:`).
+- [ ] Email field is locked to `invited_email` — frontend doesn't even render an editable input.
+- [ ] OAuth path requires the provider's email to match `invited_email`; mismatch returns the same `invite_email_mismatch` error from Phase 1.
+- [ ] Successful accept lands on `/?welcome=teammate`; the dashboard shows a "Welcome to {account_name}" toast and a checklist with "Setup shop" + "Invite a teammate" auto-marked done.
+
+**Integration tests (Playwright):**
+
+- `accept invite with email/password → join existing account → land on /?welcome=teammate`
+- `accept invite with Google OAuth (matching email) → land on dashboard`
+- `accept invite with mismatched email → see invite_email_mismatch error`
+- `accept invite with expired code → see resend message`
+
+**Commit:** `feat(auth): add /accept-invite page + lookup endpoint`
+
+---
+
+### Task 37: Email verification surfaces — banner, wall, /verify-email route
+
+**Outcome:** UI for the soft 7-day grace + day-7 wall.
+
+**Contract:**
+
+- **`<EmailVerificationBanner />`** — thin top-of-dashboard bar visible when `users.email_verified_at IS NULL` AND grace not expired. "Resend" link calls existing `POST /auth/email/send-verification`.
+- **`<EmailVerificationWall />`** — full-content replacement when grace expired. Same "Resend" CTA + a "Sign out" button.
+- **`/verify-email?token=...`** — frontend route that calls existing `POST /auth/email/verify` and shows success/error state. On success, refreshes the auth store and redirects to `/?verified=1` toast.
+
+**Acceptance criteria:**
+
+- [ ] Banner contrasts well in dark theme (use `bg-warning-dim` per design tokens, not custom colors).
+- [ ] Wall has a "Sign out" button so a user with a typo'd email can recover.
+- [ ] Verification success toast does not double-fire on remount.
+- [ ] If user is already verified when hitting `/verify-email`, the page shows "Already verified" rather than failing.
+
+**Integration tests (Playwright):**
+
+- `unverified day-1 user sees banner on dashboard`
+- `unverified day-8 user sees wall, can sign out, can resend`
+- `clicking verification link verifies and redirects to dashboard with toast`
+
+**Commit:** `feat(auth): add email verification banner, wall, /verify-email page`
+
+---
+
+## Phase L — Welcome wizard
+
+### Task 38: Wizard scaffold + Step 1 (Your shop)
+
+**Outcome:** Authed users at `/welcome` see a deliberate first-impression flow that captures shop context.
+
+**Routing:**
+
+```
+/welcome              → redirects to next incomplete step or "/" if done
+/welcome/step-1       → "Your shop"
+/welcome/step-2       → "Your PSA"
+/welcome/step-3       → "Invite your team"
+```
+
+A top-level `<WelcomeRouter />` reads `users.onboarding_step_completed` + `users.onboarding_dismissed` from authStore and dispatches:
+
+| State | Redirect |
+|---|---|
+| `onboarding_dismissed === true` | `/` |
+| `onboarding_step_completed >= 3` | `/` |
+| `onboarding_step_completed === null/0` | `/welcome/step-1` |
+| `onboarding_step_completed === 1` | `/welcome/step-2` |
+| `onboarding_step_completed === 2` | `/welcome/step-3` |
+
+**Step 1 fields (per spec):**
+
+- Company name (pre-filled from `accounts.name`, editable)
+- Team size: select from `1-2 / 3-5 / 6-10 / 11-25 / 26+`
+- Your role: select from `Owner / Lead Tech / Tech / Other`
+
+**Step 1 actions:**
+- **Continue** → PATCH `/users/me/onboarding-step` `{step: 1, action: "complete", data: {...}}` → `/welcome/step-2`
+- **Skip** → PATCH `{step: 1, action: "skip"}` → `/welcome/step-2`
+- **Skip the rest** → POST `/users/me/onboarding-dismiss-rest` → `/`
+
+**Acceptance criteria:**
+
+- [ ] Each navigation persists state server-side before transition; refresh resumes correctly.
+- [ ] Skip-the-rest is a quiet text link, not a primary button.
+- [ ] Email-verification banner is visible above the wizard if user is unverified (banner persists into wizard).
+
+**Integration tests (Playwright):**
+
+- `new user lands on /welcome/step-1 after register`
+- `step-1 Continue with all fields filled persists and advances`
+- `step-1 Skip-the-rest dismisses and lands on /`
+- `refresh in middle of step-1 returns to step-1 with prior data still in form (or empty if not yet saved)`
+
+**Commit:** `feat(onboarding): add welcome wizard scaffold + Step 1 (Your shop)`
+
+---
+
+### Task 39: Wizard Steps 2 (Your PSA) and 3 (Invite team)
+
+**Outcome:** Wizard is complete; users can finish or skip individual steps.
+
+**Step 2 fields (per spec):**
+
+- PSA selection: tiles for `ConnectWise / Autotask / HaloPSA / No PSA yet`. Selecting one shows a quiet inline "Connect now" link that navigates to `/account/integrations` (out of wizard).
+
+**Step 3 fields (per spec):**
+
+- Email input rows × 3, with "+ Add another" up to 10 max
+- Per-row role select: default "Tech" (maps to `engineer`), with "Viewer" option
+- "Skip" and "Skip the rest" links
+
+**Step 3 submit behavior:**
+
+- POST `/api/v1/accounts/me/invites/bulk` with the populated rows.
+- Then PATCH `/users/me/onboarding-step` `{step: 3, action: "complete"}`.
+- On success → `/?welcome=true` (shows a "You're all set" toast).
+- Bulk endpoint's `failed[]` array displayed inline next to the failed email; user can retry.
+
+**Acceptance criteria:**
+
+- [ ] Step 2 default action is "Continue" (not "Connect now"); the inline credential entry is intentionally NOT in the wizard.
+- [ ] Step 3 invites are sent (email send happens server-side per Phase 1 Task 22).
+- [ ] Empty Step 3 + Skip = no invites sent; step still advances.
+- [ ] Each step's persistence is independent — navigating back via browser back button respects `onboarding_step_completed`.
+
+**Integration tests (Playwright):**
+
+- `step-2 select ConnectWise → continue → primary_psa is set in /billing/state-equivalent or /auth/me`
+- `step-3 enter 2 emails → invites visible in /accounts/me/invites + emails sent`
+- `step-3 with one bad email shows partial success, user can retry`
+- `wizard end-to-end: register → step-1 → step-2 → step-3 → dashboard with success toast`
+
+**Commit:** `feat(onboarding): add wizard Steps 2 (PSA) and 3 (Invite team)`
+
+---
+
+## Phase M — Dashboard redesign
+
+### Task 40: Topbar trial pill + email verification banner integration
+
+**Outcome:** Every authed page shows the right billing-state pill in the topbar.
+
+**Contract — `<TrialPill />` placement:**
+
+Mounts inside `AppLayout` topbar. Reads `useTrialBanner()`:
+
+| Stage | Pill |
+|---|---|
+| `pristine` | "Pro trial · Nd" — info color |
+| `warning` (≤3d) | "Pro trial · Nd" — warning amber |
+| `urgent` (≤1d) | "Pro trial · today" — urgent (warning amber, slightly more saturated) |
+| `expired` | "Trial expired — pick a plan" — clickable → `/account/billing/select-plan` |
+| `paid` | tier display name (e.g., "Pro") — quiet |
+| `complimentary` | "Complimentary Pro" — friendly tag, no CTA |
+| `past_due` | "Payment failed — update card" — clickable → `/account/billing` |
+| `canceled` | "Reactivate" — clickable → `/account/billing/select-plan` |
+| `null` | hidden |
+
+**Acceptance criteria:**
+
+- [ ] Color tokens are existing design-system tokens (`--accent` / `--warning` / etc.) — no custom colors.
+- [ ] Pill is keyboard-focusable for clickable variants.
+- [ ] EmailVerificationBanner from Task 37 sits BELOW the topbar, ABOVE main content. Both can coexist.
+- [ ] Mobile: pill collapses to icon + tooltip when topbar is too narrow.
+
+**Integration tests (Playwright):**
+
+- `complimentary user sees "Complimentary Pro" pill`
+- `trialing user with 12 days remaining sees "Pro trial · 12d"`
+- `expired-trial user sees clickable "Trial expired" pill`
+- `past_due user sees clickable "Payment failed" pill`
+
+**Commit:** `feat(dashboard): add TrialPill in AppLayout topbar`
+
+---
+
+### Task 41: Next-step card + checklist redesign + dashboard wiring
+
+**Outcome:** Dashboard surfaces a single "next thing to do" card; full checklist available behind a toggle. Replaces the existing `OnboardingChecklist` component.
+
+**Contract:**
+
+- **`<NextStepCard />`** at top of dashboard content (below banner). Reads from existing `/users/onboarding-status` payload (extended in Phase 1 to drop SOLO/TEAM split — see Phase 1 Task wiring if needed; if not done, do it here).
+- Shows the highest-priority incomplete item with a primary CTA button. Items in priority order:
+  1. Verify your email (only if unverified — hidden for OAuth signups)
+  2. Set up your shop (`onboarding_step_completed >= 1`)
+  3. Run your first FlowPilot session (existing `ran_session` check)
+  4. Connect your PSA (existing `connected_psa` check)
+  5. Invite a teammate (extend existing `invited_teammate` check)
+  6. Pick a plan — surfaces near trial end (only when stage is `warning` / `urgent` / `expired`)
+- Below the card, "Show all setup steps" toggle expands a full checklist view (single list, no SOLO/TEAM split per spec).
+
+**OnboardingChecklist component changes:**
+
+- Remove `SOLO_ITEMS` / `TEAM_ITEMS` split — single unified list.
+- Drop the stale `tried_ai_assistant` / "Check out the Script Builder" item entirely.
+- Add "Pick a plan" item that shows when trial-banner stage is `warning` or later.
+
+**Backend addition:**
+
+`/api/v1/users/onboarding-status` (existing endpoint) response shape extended:
+
+```python
+class OnboardingStatus(BaseModel):
+    # existing
+    created_flow: bool
+    ran_session: bool
+    exported_session: bool
+    invited_teammate: bool
+    connected_psa: bool
+    is_team_user: bool         # KEEP — internal logic only; no UI bifurcation
+    dismissed: bool            # users.onboarding_dismissed
+    # NEW
+    email_verified: bool
+    shop_setup_done: bool      # users.onboarding_step_completed >= 1
+    # REMOVED from new code paths (kept in payload for backward-compat during deploy):
+    # tried_ai_assistant: bool
+```
+
+**Acceptance criteria:**
+
+- [ ] Old `OnboardingChecklist` widget is replaced wholesale on the dashboard route. Other pages that referenced it (none found in current code, but confirm via grep) are updated or unaffected.
+- [ ] Next-step card disappears when all items are done OR `onboarding_dismissed=TRUE`.
+- [ ] No SOLO/TEAM bifurcation in the checklist UI.
+- [ ] Stale "Script Builder" item is gone.
+
+**Integration tests (Playwright):**
+
+- `dashboard for new user surfaces "Verify your email" as next step`
+- `after verifying, next step is "Set up your shop"`
+- `after wizard step 1, next step is "Run your first FlowPilot session"`
+- `"Show all setup steps" expands to a 6-item list with no SOLO/TEAM headers`
+- `Pick-a-plan appears at trial day 12, urgent at day 13, primary at day 14`
+
+**Commit:** `feat(dashboard): replace checklist with next-step card + unified list`
+
+---
+
+## Phase N — Public surfaces
+
+### Task 42: Pricing page (B-style) at /pricing
+
+**Outcome:** Public pricing page lives at `/pricing`, gated by feature flag.
+
+**Contract:**
+
+Public route. Component at `frontend/src/pages/PricingPage.tsx`. Reads `plan_billing` data via a new public endpoint:
+
+```
+GET /api/v1/plans/public
+  → 200 [
+    {
+      plan: string,
+      display_name: string,
+      description: string | null,
+      monthly_price_cents: number | null,
+      annual_price_cents: number | null,
+      max_seats: number | null,        // from plan_limits
+      sort_order: number,
+      is_public: true,                 // filtered server-side
+    },
+    ...
+  ]
+```
+
+Page sections (per spec B):
+1. Hero (one-liner + reverse-trial reassurance)
+2. Three plan cards (Starter / Pro recommended / Enterprise) — Pro card has "Recommended" badge; Enterprise card has "Talk to sales" CTA → `/contact-sales`
+3. Comparison table (which features in which plan) — driven by feature flag display names
+4. Single testimonial slot (placeholder until real testimonial available)
+5. Trust strip — security/compliance copy
+
+**Acceptance criteria:**
+
+- [ ] Returns 404 when `self_serve_enabled === false`.
+- [ ] Plan cards show prices from `plan_billing.monthly_price_cents`. Enterprise card hides price.
+- [ ] "Start free trial" buttons on Starter/Pro link to `/register?plan=pro` (or starter).
+- [ ] "Talk to sales" on Enterprise links to `/contact-sales`.
+- [ ] Trust strip claims should be honest — see spec open-risks #7 (GDPR DPA) and #7b (SOC2). If those aren't ready by cutover, copy in this task uses softer language (e.g., "Built on Stripe + AWS · Encrypted in transit and at rest").
+
+**Integration tests (Playwright):**
+
+- `unauth user sees pricing page when self_serve_enabled is true`
+- `pricing page → "Start free trial" → /register?plan=pro`
+- `pricing page → "Talk to sales" → /contact-sales`
+- `pricing page returns 404 when self_serve_enabled is false`
+
+**Commit:** `feat(pricing): add /pricing page (B-style)`
+
+---
+
+### Task 43: Talk-to-sales form at /contact-sales + landing-page CTA
+
+**Outcome:** Enterprise prospects have a clear path; `LandingPage.tsx` gets a "See pricing" CTA.
+
+**Contract:**
+
+`/contact-sales` route with form posting to `POST /sales-leads` (Phase I Task 29).
+
+Form fields:
+- Name (required)
+- Work email (required)
+- Company (required)
+- Team size (select; same buckets as wizard Step 1 + a "more than 26" option)
+- "What brought you here?" (textarea, optional)
+- Submit button
+
+After submit:
+- Confirmation page: "Thanks — we'll reach out within 1 business day. Want to skip ahead? [Calendly link]"
+- Calendly link is a config string (`VITE_CALENDLY_URL`); when unset, link section is hidden.
+
+`LandingPage.tsx` modification:
+- Add a prominent "See pricing" CTA near the existing "Get started" CTA.
+- Both visible regardless of `self_serve_enabled` (see-pricing 404s if flag off, landing keeps existing behavior). Actually: gate the See-pricing CTA behind `useAppConfig().self_serve_enabled` so we don't show a button that 404s.
+
+**Acceptance criteria:**
+
+- [ ] Form blocks duplicate submissions client-side (disable button while in flight).
+- [ ] PostHog `talk_to_sales_form_submitted` event fires with `source: 'pricing_page' | 'landing_page'` based on referrer.
+- [ ] Calendly link block hides when `VITE_CALENDLY_URL` unset.
+
+**Integration tests (Playwright):**
+
+- `submit /contact-sales form → see confirmation page → /sales-leads has new row`
+- `landing page shows "See pricing" CTA when self_serve_enabled, hides when off`
+
+**Commit:** `feat(sales): add /contact-sales form + landing page CTA`
+
+---
+
+### Task 44: Beta-signup deprecation
+
+**Outcome:** The legacy `beta_signup.py` endpoint redirects to register; existing waitlist gets a heads-up email.
+
+**Contract:**
+
+- `POST /api/v1/beta-signup` (existing) → keep mounted but return `307 Temporary Redirect` to `/register?from=beta`.
+- One-off admin script `scripts/email_beta_waitlist.py` that reads existing `beta_signup` table and queues "we've launched" emails to each.
+- Don't drop the table; archive in place.
+
+**Acceptance criteria:**
+
+- [ ] Existing tests against `/beta-signup` either updated to expect 307 or removed.
+- [ ] Script is idempotent (uses an `email_sent_at` field on the beta-signup row, adding it via migration if needed).
+
+**Integration tests:**
+
+- `POST /beta-signup returns 307 to /register?from=beta`
+
+**Commit:** `feat(sales): redirect beta-signup to /register; queue waitlist emails`
+
+---
+
+## Phase O — Cutover
+
+### Task 45: Stripe live-mode setup checklist (manual)
+
+**Outcome:** Stripe live-mode is configured and matches test mode. Manual step; this task tracks completion.
+
+**Checklist:**
+
+- [ ] In Stripe Dashboard (live mode):
+  - [ ] Create Products: ResolutionFlow Starter, ResolutionFlow Pro, ResolutionFlow Enterprise.
+  - [ ] Create monthly + annual recurring Prices for Starter and Pro.
+  - [ ] Enterprise has no Prices in the catalog (sales-created per customer).
+  - [ ] Enable Customer Portal: update payment method, cancel subscription, view invoices. Disable plan-switching from the portal.
+  - [ ] Register webhook endpoint at `https://api.resolutionflow.com/api/v1/webhooks/stripe` with events: `checkout.session.completed`, `customer.subscription.updated`, `customer.subscription.deleted`, `invoice.payment_failed`, `invoice.payment_succeeded`.
+  - [ ] Save the live webhook signing secret.
+- [ ] In Railway prod environment variables:
+  - [ ] `STRIPE_SECRET_KEY` (live mode key, `sk_live_...`)
+  - [ ] `STRIPE_WEBHOOK_SECRET` (live signing secret)
+  - [ ] `STRIPE_PUBLISHABLE_KEY` (live publishable key) → `VITE_STRIPE_PUBLISHABLE_KEY` for frontend builds
+  - [ ] `OAUTH_REDIRECT_BASE` = `https://resolutionflow.com`
+  - [ ] `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` for prod Google OAuth app (separate from dev/test)
+  - [ ] `MS_CLIENT_ID` / `MS_CLIENT_SECRET` for prod Microsoft OAuth app
+- [ ] Run `python -m scripts.sync_stripe_plan_ids` (Phase 1 Task 6 referenced; create if not existing) to populate `plan_billing` rows with live Stripe IDs:
+  - [ ] Pro monthly + annual price IDs
+  - [ ] Starter monthly + annual price IDs (if Starter is in scope; see open risk #14)
+  - [ ] Enterprise: stripe_product_id only, no price IDs
+
+**Acceptance criteria:**
+
+- [ ] Live webhook receives a test event (use Stripe CLI's `stripe trigger checkout.session.completed` against the live endpoint with a test customer) and is logged in `stripe_events`.
+- [ ] `plan_billing` rows query returns expected Stripe IDs for Pro tier.
+
+**No commit** — this is a deploy-time operation.
+
+---
+
+### Task 46: Internal validation pass (test mode → soft cutover via per-email allowlist)
+
+**Outcome:** Real flow exercised end-to-end against the prod backend with `SELF_SERVE_ENABLED=false`, gated to internal testers only.
+
+**Per-email allowlist mechanism:**
+
+Backend reads `INTERNAL_TESTER_EMAILS` env var (comma-separated). When `SELF_SERVE_ENABLED=false` AND `current_user.email` is in the list, treat the user as if the flag were on (e.g., bypass invite-code requirement, expose pricing page via a header check). For frontend, the `/config/public` endpoint returns `self_serve_enabled: true` for these specific authenticated users.
+
+**Validation scenarios:**
+
+- [ ] Email signup → wizard step-by-step → first FlowPilot session run → trial-end synthetic time (DB query: `UPDATE subscriptions SET current_period_end = now() - interval '1 day' WHERE account_id = ...`) → plan picker → Stripe Checkout (test card `4242 4242 4242 4242`) → webhook → status='active'.
+- [ ] Google sign-in (real Google account) → `/welcome` → wizard → dashboard.
+- [ ] Microsoft sign-in (real M365 account) → same flow.
+- [ ] Invite-by-email: existing tester invites a teammate → teammate receives email → clicks link → `/accept-invite` → set password → joins account → lands on `/?welcome=teammate`.
+- [ ] Email match enforcement: try to register with `account_invite_code` and a different email → see `invite_email_mismatch`.
+- [ ] Past-due simulation: use Stripe test card `4000 0000 0000 0341` → first invoice succeeds, next charge declines → `subscription_status='past_due'` → topbar pill changes → user can update card via Customer Portal.
+- [ ] Pilot complimentary: log in as an existing pilot account → see "Complimentary Pro" pill, no walls, no nudges.
+- [ ] Webhook signature failure: send a forged webhook → 400 + log entry.
+- [ ] OAuth-only user attempts password login: rejected with `use_oauth_provider`.
+
+**Acceptance criteria:**
+
+- [ ] All 9 scenarios pass in prod test mode with internal testers.
+- [ ] Errors logged during validation are reviewed and either fixed or documented.
+
+**No commit** — validation is a checklist of test runs.
+
+---
+
+### Task 47: Feature-flag flip + week-1 monitoring
+
+**Outcome:** `SELF_SERVE_ENABLED=true` and `VITE_SELF_SERVE_ENABLED=true` in prod. Public pricing page is live.
+
+**Cutover steps:**
+
+- [ ] Send pre-launch email to all pilot users via `EmailService.send_complimentary_account_announcement` (1-2 days before flip).
+- [ ] Schedule the flip during low-traffic hours.
+- [ ] Update Railway env vars: `SELF_SERVE_ENABLED=true` (backend), `VITE_SELF_SERVE_ENABLED=true` (frontend, requires redeploy since Vite bakes at build time).
+- [ ] Verify prod: pricing page returns 200; new user can register without invite code.
+- [ ] Announce launch (founder action; not eng).
+
+**Week-1 monitoring (PostHog dashboards):**
+
+- [ ] Funnel: `pricing_page_viewed → register_started → register_completed → email_verification_completed → welcome_wizard_completed → first_session_started`
+- [ ] OAuth method mix
+- [ ] Wizard skip rate per step
+- [ ] `feature_gate_blocked` count by `flag_key`
+- [ ] Trial conversion: `trial_modal_shown → checkout_completed`
+- [ ] Stripe webhook error rate (Sentry alert if > 1/hour)
+- [ ] `subscriptions.is_paid` audit query (manual SQL): confirm complimentary accounts are NOT counted in MRR
+
+**Rollback plan:**
+
+- Flip both flags back to `false`. Pricing page → 404. Register page → invite-code-required flow. Pilot complimentary status preserved (benign).
+- Stripe webhook handler stays live regardless.
+- Forward-only schema means nothing to revert at the DB level.
+
+**No commit** — this is a deploy + monitor task.
+
+---
+
+## Self-Review
+
+**Spec coverage check (against `2026-05-05-self-serve-signup-onboarding-design.md`):**
+
+| Spec section | Covered by |
+|---|---|
+| §3.1 Pricing page | Task 42 |
+| §3.2 Register page redesign with OAuth + invite-code-optional | Task 35 |
+| §3.3 Welcome wizard (3 steps) | Tasks 38, 39 |
+| §3.4 Dashboard with topbar pill + next-step card | Tasks 40, 41 |
+| §3.5 Email verification surfaces | Task 37 |
+| §3.6 Trial-end conversion (in-app modal day 10, wall day 14) | Task 41 covers checklist; the modal is part of Task 40's TrialPill stage transitions + the dashboard's modal trigger via `useTrialBanner` — implementer's discretion to add a `<TrialEndingModal />` component if it emerges naturally |
+| §3.7 Plan picker → Stripe Checkout | Frontend page at `/account/billing/select-plan` lives within the dashboard area; Task 41's "Pick a plan" CTA navigates there. Component exists in scope of Task 40/41 — implementer's call on whether to split into its own file. |
+| §3.8 Past-due / dunning | Task 40 (TrialPill `past_due` stage) + Customer Portal link |
+| §3.9 Sales lead | Tasks 29, 43 |
+| §3.10 Owner transfer (existing) | No new task — surface in Account → Team page during dashboard work, implementer's discretion |
+| §4 BillingService.open_customer_portal | Task 27 |
+| §4 PATCH /users/me/onboarding-step | Task 28 |
+| §4 GET /billing/state consumed by frontend | Task 32 |
+| §4 useFeature/useFeatureLimit/useTrialBanner | Task 33 |
+| §4 FeatureGate / UpgradePrompt | Task 34 |
+| §4 Caching invalidation triggered from /admin/plan-limits | Task 30 |
+| §5 Beta-signup deprecation | Task 44 |
+| §5 SELF_SERVE_ENABLED dark launch | Task 31 |
+| §5 Stripe live-mode setup | Task 45 |
+| §5 Internal validation phase | Task 46 |
+| §5 Cutover + monitoring | Task 47 |
+
+**Gaps and judgment-calls (called out for implementer):**
+
+- **`<TrialEndingModal />` (day-10 in-app modal)** — left to implementer to decide whether it's its own task or rolled into Task 40. Spec is clear about behavior; component split is style.
+- **Plan picker page (`/account/billing/select-plan`)** — frontend page that calls `POST /billing/checkout-session` and redirects. Lives within Task 40/41 area; not its own task. Acceptance: "user can pick Starter/Pro + seats and be redirected to Stripe Checkout."
+- **Owner-transfer surface in Account → Team page** — existing endpoint, just needs UI. Implementer's call on which task absorbs this.
+- **`<TrialEndedWall />`** — referenced in spec; renders on dashboard route when trial expired. Lives in Task 40/41 area as a render-branch of the dashboard layout.
+
+**Placeholder scan:** none — every "implementer's discretion" call is bounded by a contract and acceptance criteria.
+
+**Type/contract consistency:**
+
+- `BillingState` shape in Task 32 matches `BillingStateResponse` from Phase 1 Task 24.
+- `PATCH /users/me/onboarding-step` payload in Task 28 matches the wizard's writes in Tasks 38, 39.
+- OAuth callback contract in Task 35 matches Phase 1 Task 17/18 endpoint shapes.
+- `<EmailVerificationGate>` in Task 34 reads from authStore; `<TrialPill>` in Task 40 reads from `useBillingStore`. Different sources, intentional (verification is on `User`, trial is on `Subscription`).
+
+---
+
+## Execution Handoff
+
+**Plan complete and saved to `docs/superpowers/plans/2026-05-06-self-serve-signup-phase-2-frontend-cutover.md`.**
+
+This plan is intentionally higher-altitude than Phase 1: contracts and acceptance criteria, not component-detail walkthroughs. Implementers exercise judgment on internal structure as long as contracts hold and integration tests pass.
+
+**Recommended execution sequence:**
+
+1. **Phase 1 first** (`2026-05-06-self-serve-signup-phase-1-backend.md`). Phase 2 depends on its endpoints.
+2. After Phase 1 lands, **execute Phase 2 phases I → O sequentially**. Each phase is one or a few mergeable PRs.
+3. **Cutover (Phase O)** is gated by Phase 1 + Phase 2 both green in prod test mode.
+
+**Two execution options for Phase 2:**
+
+**1. Subagent-Driven (recommended)** — fresh subagent per task with two-stage review. Higher-altitude tasks pair well with this since the subagent has room to make local design decisions inside the contract.
+
+**2. Inline Execution** — execute tasks in a long-running session using executing-plans, with checkpoints between phases.
+
+**Which approach?**

docs/superpowers/specs/2026-05-05-self-serve-signup-onboarding-design.md

@@ -0,0 +1,904 @@
+# Self-Serve Signup & Onboarding — Design Spec
+
+**Date:** 2026-05-05
+**Status:** Draft (revised after review-findings pass; pending user re-review)
+**Author:** Michael Chihlas + Claude
+
+---
+
+## Overview
+
+Open ResolutionFlow to public self-serve signup with a 14-day reverse trial on Pro, Stripe-backed billing, a sales-assist lane for Enterprise, and a hybrid onboarding flow (3-step welcome wizard + dashboard with next-step card). The current invite-code-gated registration is removed; existing pilot users transition to a permanent `subscriptions.status='complimentary'` state. **The billing layer reuses existing infrastructure** (`subscriptions` + `plan_limits` + `feature_flags` + `plan_feature_defaults` + `account_feature_overrides` + `account_invites` + `email_verification_tokens`) — this spec adds only what's missing, not parallel structures.
+
+---
+
+## Decisions Made
+
+| Question | Decision |
+|---|---|
+| Trigger for redoing signup/onboarding | Open self-serve channel (D); must look trustworthy; must hook into payment processor cleanly |
+| Trial / payment model | A + E — reverse trial (14 days, no card upfront) + sales-assist lane for Enterprise |
+| Plan structure | Two self-serve tiers (Starter, Pro) per seat + sales-assist Enterprise. Defined via existing `plan_limits.plan` keys + a new `plan_billing` sibling table (Stripe IDs, prices, public catalog metadata). |
+| Payment processor | Stripe with hosted Checkout; no provider abstraction |
+| Auth strategy | Stay with custom auth. Extend existing email verification (auto-send on register, 7-day soft grace + dashboard wall). Add Google + Microsoft via new `oauth_identities` table; `users.password_hash` becomes nullable with explicit OAuth-only handling in login/change-password/reset. Extend existing `account_invites` (enforce email match at register, wire `EmailService` into create/bulk). |
+| Signup form scope | A — minimal form (treat all signups as team-of-1) |
+| Plan choice timing | X — defer; trial runs on full Pro; picker shown around day 12 and at trial-end |
+| Feature gating | **Reuse existing `feature_flags` + `plan_feature_defaults` + `account_feature_overrides`.** Admin via existing `/admin/plan-limits` + `/admin/feature-flags` endpoints. No new combined `/admin/plans` surface in v1. |
+| Onboarding shape | C — hybrid (3-step welcome wizard then dashboard with checklist) |
+| Welcome wizard layout | V2 — narrative 3 steps (Your shop, Your PSA, Invite your team) |
+| Dashboard first-run | C — topbar trial pill + single "next step" card (full checklist behind a "Show all" toggle) |
+| Email verification | Soft, 7-day grace, hard wall day 7; skipped entirely for OAuth signups (provider-attested). **Reuses existing `email_verification_tokens` table + `/auth/email/send-verification` + `/auth/email/verify`.** Backend enforcement via new `require_verified_email_after_grace` dep with path allowlist (auth, profile, billing) returns 403 when grace expires unverified. Frontend `<EmailVerificationWall />` is a UX layer over the same rule. |
+| Pricing page | B — pricing + light marketing context (comparison table + testimonial slot + trust strip) |
+| Trial-end conversion flow | A — quiet days 1-9, gentle nudges 10-13, hard wall day 14 with plan picker |
+| Trial expiry enforcement | **Replace `deps.py:109` auto-downgrade.** Expiry is computed at request time (`status='trialing' AND current_period_end < now()`); no mutation to `plan='free'`. New backend `require_active_subscription` dep with path allowlist returns 402 when locked. |
+| `is_paid` semantics | `subscriptions.is_paid` excludes `complimentary` so comp accounts don't inflate paid/MRR metrics. New `has_pro_entitlement` property covers "this account can access Pro features" (true for paid Pro + complimentary Pro + active trial). |
+| Billing state surface | **Separate `GET /billing/state` endpoint** feeding a new frontend `useBillingStore`. `/auth/me` stays user-focused. |
+| Teammate invite-accept | Set-password OR Google/Microsoft OAuth; email-locked **(enforced at `/auth/register` against `account_invites.email`)**; no welcome wizard for invitees. |
+| Existing pilot users | All transitioned to `subscriptions.status='complimentary'` on Pro — no nags, no walls, voluntary conversion path. |
+| Existing invite codes | Registration gate removed. Table preserved for historical pilots; `User.invite_code_id` retained for existing rows; not consumed at new signups. **No repurposing.** |
+| Promo codes | **Deferred from v1.** Add a new `promo_codes` table later if a launch campaign needs them. |
+
+---
+
+## Section 1 — System overview
+
+### What this delivers
+
+Public registration through `/pricing` → `/register` → `/welcome` → dashboard, with the billing substrate built almost entirely on existing infrastructure. New code is concentrated in (a) the OAuth surface, (b) Stripe-aware billing service + webhook handler, (c) the welcome wizard + dashboard redesign, and (d) the public-facing pricing page.
+
+### Four chunks of work
+
+1. **Front-of-funnel** — public `/pricing` page (B-style: comparison table + testimonial slot + trust strip), sales-lead capture form, reworked `/register` form with OAuth options.
+2. **Onboarding surfaces** — 3-step welcome wizard (V2: shop → PSA selection → invite team) firing immediately after register; redesigned dashboard with topbar trial pill + single "next-step" card (C-style); 6-item checklist (Verify email → Setup shop → Run first session → Connect PSA → Invite teammate → Pick a plan).
+3. **Billing integration over existing schema** — extend `plan_limits` with a sibling `plan_billing` table (Stripe IDs + public catalog metadata); seed Starter / Pro / Enterprise rows in `plan_limits`; seed `feature_flags` + `plan_feature_defaults` for the Pro/Starter gating split; add `subscriptions.status='complimentary'` value; replace `deps.py:109` trial-expiry mutation with computed checks; add a `BillingService`, Stripe webhook handler, and `require_active_subscription` dep. Reuses existing `/admin/plan-limits` and `/admin/feature-flags` admin surfaces.
+4. **Auth additions** — Google + Microsoft OAuth via a new `oauth_identities` table (`users.password_hash` becomes nullable). Extend existing `email_verification_tokens` flow with auto-send on register and a 7-day soft-grace dashboard wall. Extend existing `account_invites` to enforce email match at registration and to actually send the invitation email at create-time (today only resend sends).
+
+### What stays the same
+
+- Existing JWT auth + JTI refresh rotation
+- `Account` / `Team` / `User` model and the `is_super_admin` / `account_role` / `is_team_admin` permission hierarchy (with `account_role` enum `'owner' | 'admin' | 'engineer' | 'viewer'`)
+- Phase 4 RLS (subscription state lives on `subscriptions`, account-scoped — RLS rules already configured for it)
+- All product surfaces (FlowPilot, PSA integrations, sessions, flows)
+- `/admin/plan-limits` + `/admin/feature-flags` admin endpoints (extended, not replaced)
+- `/accounts/me/transfer-ownership` (existing — covers owner transfer, no longer flagged "out of scope")
+- `/accounts/me/invites` and `/me/invites/{id}/resend` (extended with email send + email-match enforcement)
+
+### What's deprecated
+
+- Invite-code-as-registration-gate. The `invite_codes` table is preserved (historical foreign keys from `users.invite_code_id`); the gate is removed at `/auth/register`.
+- `beta_signup.py` waitlist endpoint becomes a 307 redirect to `/register`.
+- The current SOLO/TEAM split in `OnboardingChecklist` (one unified list).
+- The "Check out the Script Builder" item mapped to the stale `tried_ai_assistant` key.
+- Custom card-collection forms (Stripe Checkout owns this).
+- The auto-downgrade-on-expired-trial logic in `deps.py:109` (replaced with non-mutating computed checks).
+
+### Sequencing principle
+
+The billing extensions (new columns, new dep, replacing the auto-downgrade) and the Stripe webhook handler are the longest pole and the most unfamiliar surface area. Build it first, ship it dark behind `SELF_SERVE_ENABLED=false`, then layer the funnel and onboarding surfaces once it's stable. Detailed phases live in the implementation plan.
+
+---
+
+## Section 2 — Data model
+
+### Schema additions (new, small)
+
+#### `oauth_identities`
+
+```
+id                     UUID PK
+user_id                UUID FK users
+provider               VARCHAR(20)   -- 'google' | 'microsoft'
+provider_subject       VARCHAR(255)  -- provider's stable user id
+provider_email_at_link VARCHAR(255)  -- email reported by provider at link time
+created_at, updated_at TIMESTAMP WITH TIME ZONE
+UNIQUE (provider, provider_subject)
+INDEX (user_id)
+```
+
+A user can have zero password (OAuth-only), one password, and 0+ OAuth identities. v1 ships with one identity per user (signup creates one row). Account linking is a future feature with no schema change required.
+
+#### `plan_billing` (sibling to `plan_limits`)
+
+```
+plan                       VARCHAR(50) PK FK plan_limits.plan
+display_name               VARCHAR(255) NOT NULL
+description                TEXT NULL
+monthly_price_cents        INTEGER NULL    -- nullable for Enterprise (custom)
+annual_price_cents         INTEGER NULL
+stripe_product_id          VARCHAR(255) NULL
+stripe_monthly_price_id    VARCHAR(255) NULL
+stripe_annual_price_id     VARCHAR(255) NULL
+is_public                  BOOLEAN NOT NULL DEFAULT TRUE
+is_archived                BOOLEAN NOT NULL DEFAULT FALSE
+sort_order                 INTEGER NOT NULL DEFAULT 0
+created_at, updated_at     TIMESTAMP WITH TIME ZONE
+```
+
+`plan_limits.plan` stays the canonical plan key. `plan_billing` carries the Stripe + public-catalog metadata. Joined into the existing `/admin/plan-limits` admin endpoint via the response schema (single PUT updates both tables in one transaction).
+
+#### `sales_leads`
+
+```
+id                  UUID PK
+email               VARCHAR(255) INDEXED
+name                VARCHAR(255)
+company             VARCHAR(255)
+team_size           VARCHAR(20)   -- range string from form
+message             TEXT
+source              VARCHAR(50)   -- 'pricing_page' | 'register_footer' | etc.
+posthog_distinct_id VARCHAR(255) NULL
+status              VARCHAR(20) DEFAULT 'new'  -- 'new' | 'contacted' | 'closed'
+created_at, updated_at
+```
+
+Global table. No RLS.
+
+#### `stripe_events`
+
+Webhook idempotency log. Global table.
+
+```
+id              VARCHAR(255) PK   -- Stripe event id
+event_type      VARCHAR(100) INDEXED
+processed_at    TIMESTAMP WITH TIME ZONE
+payload_excerpt JSONB
+```
+
+### Modifications to existing tables
+
+#### `subscriptions` — extend the status enum
+
+- New status value: `'complimentary'`. Status enum effectively becomes `'active' | 'trialing' | 'past_due' | 'canceled' | 'incomplete' | 'complimentary'`. The column is `String(50)` so no schema migration is required for the value itself; we update the value-level checks only.
+- `Subscription.is_active` already returns `True` for `('active', 'trialing')` — extend to include `'complimentary'`.
+- `Subscription.is_paid` (currently `plan in ('pro', 'team')`) → narrow to `plan in ('pro', 'team') AND status NOT IN ('complimentary',)`. Used for revenue / paid-customer / MRR calculations only.
+- New `Subscription.has_pro_entitlement` property: returns True for `(plan='pro' AND status IN ('active', 'complimentary'))` OR `(status='trialing' AND current_period_end > now())`. Used for "can this account access Pro features."
+
+These are model-level Python property changes plus tests; the underlying column type doesn't change.
+
+#### `users` — additions
+
+- `email_verified_at` already exists. No add. Email-verification flow uses it.
+- `password_hash` — **change `nullable=False` → `nullable=True`** to support OAuth-only users. Migration sets nullable; no data backfill needed (existing rows all have hashes).
+- `role_at_signup VARCHAR(50) NULL` — `'owner' | 'lead_tech' | 'tech' | 'other'` (welcome-wizard Step 1 captures this).
+
+The existing `users.onboarding_dismissed` field stays. **Add a new `users.onboarding_step_completed INTEGER NULL`** that tracks the highest wizard step the user has either completed or explicitly skipped (1, 2, or 3; NULL = haven't started). This is the only new column needed beyond `role_at_signup` and resolves the per-step skip ambiguity that derived data couldn't represent.
+
+Wizard state model:
+
+- User clicks **Continue** on a step → `onboarding_step_completed = step_number`. Step's data fields are written (e.g., Step 1 writes `users.role_at_signup` + `accounts.team_size_bucket`).
+- User clicks **Skip** on a step → `onboarding_step_completed = step_number`. Step's data fields stay NULL.
+- User clicks **Skip the rest** on any step → `users.onboarding_dismissed = TRUE` (whatever step they were on stays as `onboarding_step_completed = step_number - 1`).
+- Wizard is "done" when `onboarding_dismissed = TRUE` OR `onboarding_step_completed >= 3`.
+- `/welcome` redirect logic: if done, go to `/`; otherwise go to `/welcome/step-{onboarding_step_completed + 1 or 1}`.
+
+This makes "I intentionally skipped inviting teammates" representable separately from "I haven't reached Step 3 yet."
+
+#### `accounts` — additions for wizard data
+
+`accounts.name` (existing, `String(255) NOT NULL`) is reused for the wizard's "Company name" field — the wizard updates this row rather than a new column. Today `accounts.name` is populated at register-time from the user's input or a sensible default; the wizard lets the user correct it.
+
+New columns:
+
+- `team_size_bucket VARCHAR(20) NULL` — `'1-2' | '3-5' | '6-10' | '11-25' | '26+'`
+- `primary_psa VARCHAR(20) NULL` — `'connectwise' | 'autotask' | 'halopsa' | 'none'`
+
+No billing state on `accounts` — it lives on `subscriptions`.
+
+#### `account_invites` — small additions
+
+- `revoked_at TIMESTAMP WITH TIME ZONE NULL` — distinguishes revoked from used. Current model has only `used_at`; revoke (resend handler at `accounts.py:323`) currently deletes the row. Add `revoked_at` + change resend to soft-revoke for audit trail.
+- (Optional) `email_sent_at TIMESTAMP WITH TIME ZONE NULL` — track that the invite email was actually sent (today, only resend sends; create does not).
+
+`AccountInvite.is_used` and `is_valid` properties extend to consider `revoked_at`.
+
+### Migrations
+
+Single Alembic chain — manual revisions per Lesson 77. Multi-head heads on `main` (`070`, `c0f3a4b7e91d`, `024`) currently coexist; the new chain branches from the most recent and merges via `alembic upgrade heads` (plural).
+
+1. `add_oauth_identities.py` — new table.
+2. `users_password_hash_nullable.py` — alter to nullable.
+3. `users_add_role_at_signup_and_onboarding_step.py` — add `role_at_signup` and `onboarding_step_completed` columns.
+4. `accounts_add_wizard_columns.py` — add `team_size_bucket`, `primary_psa`. (`accounts.name` already exists; wizard writes to it.)
+5. `account_invites_add_revoked_at_and_email_sent_at.py` — add columns.
+6. `add_plan_billing.py` — new sibling table. Seeds Starter / Pro / Enterprise rows **with `stripe_product_id` / `stripe_*_price_id` left NULL**. Existing `plan_limits` rows already exist for `'free' / 'pro' / 'team'`; this migration aligns keys (`'starter' | 'pro' | 'enterprise'` if we rename, OR keep `'free' / 'pro' / 'team'` and treat `'free'` as the floor — open risk #14 captures the decision). Stripe IDs are populated **out-of-band** per environment via either the existing `/admin/plan-limits` PUT (extended to accept Stripe fields) or a one-off `python -m scripts.sync_stripe_plan_ids` admin command driven by env vars. **Migrations stay environment-agnostic** — they don't read live mode vs. test mode IDs.
+7. `seed_pro_starter_feature_flags.py` — register feature keys (`psa_integration`, `escalation_mode`, `script_builder`, `analytics_dashboards`, `knowledge_flywheel`, `team_admin_full`, `monthly_sessions` quantitative, `seats` quantitative, `sso`, `audit_log`) in `feature_flags`; populate `plan_feature_defaults` per the Pro/Starter split.
+8. `subscriptions_pilot_complimentary_backfill.py` — `UPDATE subscriptions SET status='complimentary', plan='pro' WHERE status NOT IN ('canceled')` for accounts that exist as of cutover. Single statement; ≤ 100 rows expected.
+9. `add_sales_leads_and_stripe_events.py` — two new tables.
+
+Forward-only. No down-migrations for the data backfills (step 8) — the original status values per account are not preserved.
+
+### RLS notes
+
+- `oauth_identities` is account-adjacent (joined via `user_id`), but RLS on `users` is admin-DB-only (per `deps.py` `get_current_user` uses `get_admin_db`). Treat `oauth_identities` the same — no per-tenant RLS policy; queries use admin session. Verify against current `users` table policy before merging.
+- `plan_billing` is global (joins `plan_limits.plan`, also global). No RLS.
+- `sales_leads`, `stripe_events` are global. No RLS.
+- `account_invites` already has its policy (account-scoped). No change.
+- `subscriptions` already has its policy. No change to schema means no RLS revision.
+
+### Index notes
+
+- `oauth_identities (provider, provider_subject)` UNIQUE — the OAuth callback's primary lookup.
+- `oauth_identities (user_id)` — list a user's identities.
+- `account_invites (revoked_at)` — partial filter for active-invites queries (`WHERE accepted_by_id IS NULL AND revoked_at IS NULL`).
+
+---
+
+## Section 3 — Funnel walkthrough
+
+### 1. Acquisition — `/pricing` (public)
+
+New route. B-style page: hero (one-liner + reverse-trial reassurance), three plan cards (Starter / Pro recommended / Enterprise), comparison table, testimonial slot (placeholder copy until a real one lands), trust strip ("SOC2 in progress · Stripe billing · GDPR DPA available"). Plan card data sourced from `plan_billing` filtered by `is_public=TRUE AND is_archived=FALSE`.
+
+- **Pro/Starter cards** → "Start free trial" → `/register?plan=pro` (or `?plan=starter`). Query param remembered through OAuth round-trip.
+- **Enterprise card** → "Talk to sales" → `/contact-sales` → POST `/sales-leads` → confirmation page with Calendly link in the email.
+- Existing `LandingPage.tsx` gets a "See pricing" CTA pointing here.
+
+### 2. Registration — `/register` (public, redesigned)
+
+Three sign-up paths on one page:
+
+- **Google sign-in** (primary button at top) → OAuth round-trip → `/auth/google/callback`. Backend creates a User if first time (`oauth_identities` row + Account + Subscription on Pro trial via `BillingService.start_trial`), marks `email_verified_at = now()` (provider-attested), redirects to `/welcome`.
+- **Microsoft sign-in** (button) → same flow with `provider='microsoft'`.
+- **Email + password** → POST `/auth/register`. Backend creates User (with `password_hash` set) + Account, calls `BillingService.start_trial`, sends verification email via existing `EmailService.send_email_verification_email` (auto-send is added; today the user has to click a button), returns JWT, frontend redirects to `/welcome`.
+
+Form fields: full name, work email, password (10+ chars, complexity rules per existing `UserCreate.password_complexity` validator). The current `invite_code` field on `UserCreate` is **removed at the registration gate** — public signups don't need one. The `account_invite_code` field is **kept** for the teammate-accept flow (see step 5b below).
+
+**Critical fix flagged in review:** registration with `account_invite_code` must enforce `user_data.email == account_invites.email` (today this is not enforced at `/auth/register`). The check happens in the register handler before the User is created; mismatch returns 400 with `{"error": "invite_email_mismatch"}`.
+
+### 3. Welcome wizard — `/welcome` (authed)
+
+Dedicated routes: `/welcome/step-1` (Your shop), `/welcome/step-2` (Your PSA), `/welcome/step-3` (Invite team). `/welcome` itself redirects to the lowest-numbered incomplete step. Each step persists immediately (PATCH endpoints — see Appendix A) so refreshes don't lose data and "Skip the rest" lands cleanly.
+
+- **Step 1 — Your shop**: company name (pre-filled from existing `accounts.name`, editable), team size bucket, your role. Saves to `accounts.name`, `accounts.team_size_bucket`, `users.role_at_signup`.
+- **Step 2 — Your PSA**: PSA selection only. Saves to `accounts.primary_psa`. Quiet "Connect now" link → `/account/integrations` (out of wizard); default action is **Continue**. No API key entry inside the wizard.
+- **Step 3 — Invite your team**: up to 3 email fields visible with "+ Add another" link; each invite defaults to "Tech" role; fully skippable. POSTs to a new `POST /accounts/me/invites/bulk` (thin wrapper around the existing single-create) **and sends invite emails per row**. The wizard's "Tech" UI label maps to `account_invites.role = 'engineer'` in the DB; "Viewer" UI label maps to `'viewer'` (per the existing CHECK constraint).
+
+**Critical fix flagged in review:** today, `POST /accounts/me/invites` (`accounts.py:257`) creates the row but does NOT send the email — only `/me/invites/{id}/resend` sends. The new flow wires `EmailService.send_account_invite_email` (existing method at `core/email.py:125`) into both create and bulk paths and stamps `email_sent_at` on success.
+
+Skip behavior: "Skip" on a step advances `users.onboarding_step_completed` (recording that the user saw and chose to skip that step). A separate "Skip the rest, take me to dashboard" link sets `users.onboarding_dismissed=TRUE` and redirects to `/`. Wizard is "done" when `onboarding_dismissed=TRUE` OR `onboarding_step_completed >= 3`. Auth-store reads this state on app load; `/welcome` redirects to the next incomplete step or to `/` if done.
+
+**Invited teammate variant:** invitee's email link goes to a frontend `/accept-invite?code=…` route that posts to `/auth/register` with `account_invite_code` (per the existing `UserCreate` schema). They land on `/?welcome=teammate` instead of the wizard, and get a brief "Welcome to {company}'s ResolutionFlow" toast. Re-running the wizard on already-onboarded users is suppressed via `users.onboarding_dismissed` OR derived data presence.
+
+### 4. Dashboard — `/` (authed, redesigned)
+
+- **Topbar pill** in `AppLayout` renders based on `subscriptions.status` and `current_period_end`:
+  - `trialing` AND `current_period_end > now()`: "Pro trial · Nd" — blue, amber when ≤3d remaining, red when ≤1d.
+  - `trialing` AND `current_period_end <= now()`: "Trial expired — pick a plan" (the locked state — no mutation has occurred at the DB level, just rendered differently).
+  - `active`: tier name only ("Pro" / "Starter") — no urgency.
+  - `complimentary`: "Complimentary Pro" — friendly tag, no CTA.
+  - `past_due`: "Payment failed — update card" — clickable, routes to `/account/billing`.
+  - `canceled`: pill becomes a "Reactivate" CTA.
+- **Next-step card** sits below the topbar. "Show all setup steps" link expands the full 6-item list inline.
+- **Email-verification banner** (when `users.email_verified_at IS NULL`): always-visible thin bar above the next-step card with a "Resend" link (POSTs to existing `/auth/email/send-verification`). On day 7 unverified, the dashboard route renders `<EmailVerificationWall />` instead of normal content.
+
+Checklist items (same for everyone — no SOLO/TEAM split):
+
+1. **Verify your email** — auto-completes on link click; hidden if signed up via OAuth.
+2. **Set up your shop** — completes when `users.onboarding_step_completed >= 1`.
+3. **Run your first FlowPilot session** — the wedge. Highlighted as the headline action when prior items are complete.
+4. **Connect your PSA** — auto-completes when first PSA connection saved. Pre-fills the provider based on welcome wizard selection.
+5. **Invite a teammate** — auto-completes when first invitation is sent.
+6. **Pick a plan** — appears earlier with low emphasis; turns urgent at ≤3 days remaining in trial.
+
+The stale `tried_ai_assistant` / "Check out the Script Builder" item is dropped entirely.
+
+### 5. Email verification — existing endpoints, new gating
+
+- `POST /auth/email/send-verification` (existing, `auth.py:621`) is auto-called by `/auth/register` — today the user has to click a button.
+- `POST /auth/email/verify` (existing, `auth.py:662`) consumes the token and sets `users.email_verified_at`.
+- The frontend `/verify-email?token=…` route calls the existing endpoint and shows a success or error state.
+- New: a frontend gating layer (`<EmailVerificationGate />`) wraps the dashboard route. Day 1-6 unverified shows the soft banner; day 7+ unverified renders `<EmailVerificationWall />`.
+- **Backend enforcement** via the new `require_verified_email_after_grace` dep (Section 4). The frontend wall is UX; the backend dep prevents direct API access by an unverified user past the 7-day grace. Mounted on every protected router; allowlists `/auth/*` (logout, verify, send-verification, password change), `/users/me`, and `/billing/*` so the user can still log out, verify, manage their profile, and convert to paid.
+
+No new endpoints, no new column. One new backend dep.
+
+### 6. Trial-end — Days 10-14
+
+- **Day 10**: in-app modal once ("Your trial ends in 4 days. Pick a plan to keep going."). Fired by `useTrialBanner` hook reading from `useBillingStore` (which polls `GET /billing/state`); per-user dismiss recorded in localStorage. Email day 10 + day 13 (`EmailService.send_trial_ending`).
+- **Day 14**: when `subscriptions.status='trialing'` AND `current_period_end < now()`, the dashboard route renders `<TrialEndedWall />` with the plan picker (Starter / Pro radio + seat count input). **No DB mutation occurs** — the lockout is computed at request time. Past sessions remain visible read-only for 30 days after `current_period_end` — computed at render time as `current_period_end + INTERVAL '30 days' < now()`. After that window, sessions are still in the database (no destructive action) but the dashboard hides them behind the wall until billing is added.
+
+### 7. Plan picker → Stripe Checkout — `/account/billing/select-plan` (authed)
+
+User picks Starter/Pro + seat count → POST `/billing/checkout-session` → backend calls `stripe.checkout.sessions.create` with:
+
+- `customer_email` from User
+- `line_items` (price_id from `plan_billing` × quantity = seats)
+- `mode='subscription'`
+- `subscription_data.trial_end = current_period_end` if still in trial (Stripe takes over the trial countdown)
+- `success_url=/account/billing?success=1`, `cancel_url=/account/billing/select-plan`
+
+Frontend redirects to Stripe-hosted Checkout. Stripe `checkout.session.completed` webhook → backend updates `subscriptions.status='active'`, sets `stripe_subscription_id`, `stripe_price_id`, refreshes `current_period_start/end` from the Stripe subscription, sets `seat_limit`. Idempotency via `stripe_events.id`.
+
+Success URL renders dashboard with "Pro active 🎉" toast.
+
+### 8. Past-due / dunning
+
+Stripe `invoice.payment_failed` webhook → `subscriptions.status='past_due'`. Topbar pill flips to "Payment failed — update card" linking to `/account/billing`, which uses Stripe's Customer Portal for card updates and cancellation. Dashboard remains accessible during the dunning window (Stripe default: 4 retries over 3 weeks). Account locks via `require_active_subscription` only at `canceled`.
+
+### 9. Sales lead — `/contact-sales` (public)
+
+Form posts to `/sales-leads` → creates row + sends email to `sales@resolutionflow.com` + emits PostHog event. Confirmation page: "Thanks — we'll reach out within 1 business day. Want to skip ahead? [Calendly link]." The Calendly link is a config string, not a calendar integration in v1.
+
+### 10. Owner transfer (existing — noted)
+
+Owner transfer is supported via the existing `POST /accounts/me/transfer-ownership` (`accounts.py:150`). The pricing-page Enterprise tier and the Account → Team page in the redesigned dashboard surface this for owners who need to hand off the account. **Not flagged as out-of-scope risk** as it was in the prior draft.
+
+---
+
+## Section 4 — Billing substrate + Stripe integration
+
+### `app.services.billing.BillingService`
+
+Single billing module — not a polymorphic provider abstraction.
+
+```python
+class BillingService:
+    @staticmethod
+    async def start_trial(db, account: Account) -> Subscription:
+        """Creates or updates the Subscription row for a new account.
+        Sets plan='pro', status='trialing', current_period_end=now()+14d.
+        Called from /auth/register (email path) and OAuth-callback flows.
+        No Stripe API call yet — Stripe Customer is created lazily at first
+        checkout."""
+
+    @staticmethod
+    async def create_checkout_session(db, account, plan, seats, billing_interval) -> str:
+        """Returns the Stripe Checkout URL. Creates Stripe Customer if missing
+        (stores stripe_customer_id on the **Account** row — existing column at
+        accounts.stripe_customer_id), then builds checkout.sessions.create
+        with line_items, mode='subscription', subscription_data.trial_end if
+        still within local trial, success/cancel URLs. Subscription row is
+        updated by the webhook handler with stripe_subscription_id and
+        stripe_price_id once checkout completes."""
+
+    @staticmethod
+    async def apply_subscription_event(db, event_type: str, payload: dict) -> None:
+        """Single entry point for every Stripe webhook that mutates subscription
+        state. Pure function of (event_type, payload) -> DB writes. Called from
+        the webhook handler after signature verification + idempotency check."""
+
+    @staticmethod
+    async def open_customer_portal(account) -> str:
+        """Returns Stripe-hosted Customer Portal URL for card updates and
+        cancellation."""
+
+    @staticmethod
+    async def get_billing_state(db, account: Account) -> BillingStateResponse:
+        """Returns the full billing snapshot for /billing/state — subscription
+        status, plan, plan_billing metadata, plan_limits values, and the
+        flattened effective feature flags (defaults overridden by
+        account_feature_overrides)."""
+```
+
+`account_id` is the canonical local key; Stripe is the canonical remote state; the webhook handler is the bridge.
+
+### Replacing the trial auto-downgrade
+
+The existing logic in `deps.py:81-129` mutates `subscriptions` on every request when a trial expires:
+
+```python
+# CURRENT (to be removed):
+if subscription.status == "trialing" and subscription.current_period_end < now():
+    subscription.plan = "free"
+    subscription.status = "active"
+    subscription.current_period_end = None
+    subscription.current_period_start = None
+    await db.commit()
+```
+
+**Replace this entire block with no-op.** Trial expiry becomes a *computed* state. The data stays as `status='trialing'`, `current_period_end` in the past — readable, observable, idempotent. The new `require_active_subscription` dep enforces the lockout.
+
+If we ever want an explicit `'expired'` status (for analytics observability), it can be added later without changing the semantic of "trialing + past current_period_end = locked."
+
+### New backend dep — `require_active_subscription`
+
+```python
+_SUBSCRIPTION_GUARD_ALLOWLIST = {
+    # auth & profile
+    "/api/v1/auth/me",
+    "/api/v1/auth/logout",
+    "/api/v1/auth/password/change",
+    "/api/v1/auth/email/send-verification",
+    "/api/v1/auth/email/verify",
+    # billing surfaces
+    "/api/v1/billing/state",
+    "/api/v1/billing/checkout-session",
+    "/api/v1/billing/portal-session",
+    # users own profile
+    "/api/v1/users/me",
+    "/api/v1/users/me/onboarding-step",
+    # read-only history (pattern match: /sessions and /trees in GET only)
+}
+
+async def require_active_subscription(
+    request: Request,
+    current_user: User = Depends(get_current_active_user),
+    db: AsyncSession = Depends(get_admin_db),
+) -> Subscription:
+    """Enforces 'this account currently has access.' Mounted on routers that
+    require Pro entitlement. Returns the Subscription row when allowed; raises
+    402 with structured payload when locked."""
+
+    if request.url.path in _SUBSCRIPTION_GUARD_ALLOWLIST:
+        return None  # bypass
+
+    sub = await _get_subscription_for_account(db, current_user.account_id)
+    if not sub:
+        raise HTTPException(402, detail={"error": "no_subscription"})
+
+    is_live = (
+        sub.status in ("active", "complimentary")
+        or (
+            sub.status == "trialing"
+            and sub.current_period_end is not None
+            and sub.current_period_end > datetime.now(timezone.utc)
+        )
+        or sub.status == "past_due"  # dunning grace — Stripe retries
+    )
+    if not is_live:
+        raise HTTPException(
+            status_code=402,
+            detail={
+                "error": "subscription_inactive",
+                "status": sub.status,
+                "plan": sub.plan,
+                "current_period_end": sub.current_period_end.isoformat() if sub.current_period_end else None,
+                "upgrade_url": "/account/billing/select-plan",
+            },
+        )
+
+    return sub
+```
+
+Mounted on every router under `/api/v1/` *except* the explicit allowlist. GET endpoints for past sessions/trees during the 30-day read-only post-expiry window need a softer variant — see Section 3 step 6 for the read-only contract. Implementation plan will identify each protected endpoint specifically.
+
+### New backend dep — `require_verified_email_after_grace`
+
+Mirror of `require_active_subscription`, but for email verification. The frontend `<EmailVerificationWall />` is a UX layer; this dep is the security layer that prevents an unverified user from bypassing the wall by hitting product APIs directly.
+
+```python
+_EMAIL_VERIFICATION_ALLOWLIST = {
+    # auth & session
+    "/api/v1/auth/me",
+    "/api/v1/auth/logout",
+    "/api/v1/auth/email/send-verification",
+    "/api/v1/auth/email/verify",
+    "/api/v1/auth/password/change",
+    # users own profile
+    "/api/v1/users/me",
+    # billing — let user manage subscription even if email unverified
+    "/api/v1/billing/state",
+    "/api/v1/billing/checkout-session",
+    "/api/v1/billing/portal-session",
+}
+
+VERIFICATION_GRACE_DAYS = 7
+
+async def require_verified_email_after_grace(
+    request: Request,
+    current_user: User = Depends(get_current_active_user),
+) -> None:
+    """Enforces 'this user has verified their email, OR is still inside the
+    7-day grace from account creation.' OAuth signups bypass cleanly because
+    /auth/google/callback and /auth/microsoft/callback set
+    users.email_verified_at = now() (provider-attested).
+    Mounted on every protected router *except* the explicit allowlist."""
+
+    if request.url.path in _EMAIL_VERIFICATION_ALLOWLIST:
+        return
+
+    if current_user.email_verified_at is not None:
+        return
+
+    grace_ends = current_user.created_at + timedelta(days=VERIFICATION_GRACE_DAYS)
+    if datetime.now(timezone.utc) < grace_ends:
+        return  # still inside grace
+
+    raise HTTPException(
+        status_code=403,
+        detail={
+            "error": "email_not_verified",
+            "grace_ended_at": grace_ends.isoformat(),
+            "resend_url": "/api/v1/auth/email/send-verification",
+        },
+    )
+```
+
+Differs from `require_active_subscription` in three ways:
+
+- **403 (Forbidden) rather than 402 (Payment Required)** — verification is identity, not billing. Lets the frontend interceptor route to a verification CTA, distinct from the upgrade CTA.
+- **No DB read** — uses fields already on the `current_user` row from `get_current_active_user`. Cheap.
+- **Allowlist includes `/billing/*`** — an unverified user past day 7 should still be able to convert to paid (verification gates feature use, not billing). The verification banner persists into Checkout if needed.
+
+The two guards compose: most routers depend on **both** `require_active_subscription` AND `require_verified_email_after_grace`. The implementation plan will identify each protected router specifically; both guards are non-optional for product surfaces.
+
+### Stripe webhook handler — `POST /api/v1/webhooks/stripe`
+
+A stub already exists at `app/api/endpoints/webhooks.py` with signature verification + an early-out when `settings.stripe_enabled=False`. This work extends the stub — does not replace it — by wiring concrete event handlers, idempotency tracking, and `BillingService.apply_subscription_event` integration.
+
+- Public endpoint; signature verification is the only gate.
+- Reads `Stripe-Signature` header → `stripe.Webhook.construct_event(payload, sig, STRIPE_WEBHOOK_SECRET)` → 400 on mismatch.
+- **Idempotency**: every event recorded in `stripe_events` keyed by Stripe's event id. If the row exists, return 200 immediately.
+- Uses `_admin_session_factory()` — no `current_account_id` is set during webhook processing (Phase 4 RLS pattern).
+- **Replay protection**: Stripe signatures embed a timestamp; reject if older than 5 min.
+
+Events handled:
+
+| Event | Action |
+|---|---|
+| `checkout.session.completed` | Activate: `subscriptions.status='active'`, set `subscriptions.stripe_subscription_id`, `subscriptions.stripe_price_id`, `subscriptions.current_period_start/end`, `subscriptions.seat_limit` from session line_items. (`accounts.stripe_customer_id` was set earlier at `create_checkout_session` time.) |
+| `customer.subscription.updated` | Reflect plan changes / period transitions / seat updates |
+| `customer.subscription.deleted` | `status='canceled'`, lock via `require_active_subscription` |
+| `invoice.payment_failed` | `status='past_due'` |
+| `invoice.payment_succeeded` | Confirm `status='active'` after dunning recovery |
+| Other | Log and ack 200 |
+
+### Backend feature-gate dep — `require_feature`
+
+Reads from the existing 3-table chain (no new tables). **`require_feature` internally composes with `require_active_subscription`** — feature gating without subscription gating would let canceled/expired-trial accounts pass feature checks. They are not independent.
+
+```python
+async def require_feature(flag_key: str):
+    async def _dep(
+        sub: Subscription = Depends(require_active_subscription),
+        user: User = Depends(get_current_active_user),
+        db: AsyncSession = Depends(get_admin_db),
+    ) -> None:
+        # require_active_subscription has already verified the account is live;
+        # sub is the live Subscription row. Now check the feature flag.
+        flag = await _resolve_flag(db, user.account_id, sub.plan, flag_key)
+        if not flag.enabled:
+            raise HTTPException(
+                status_code=402,
+                detail={
+                    "error": "feature_not_in_plan",
+                    "feature": flag_key,
+                    "current_plan": sub.plan,
+                    "upgrade_url": "/account/billing/select-plan",
+                },
+            )
+    return _dep
+
+
+async def _resolve_flag(db, account_id, plan_key, flag_key):
+    """Resolve effective feature flag value:
+    1. account_feature_overrides for (account_id, flag_key) -> if exists, use that
+    2. else plan_feature_defaults for (plan, flag_key) -> use that
+    3. else default disabled
+    """
+```
+
+Used as `Depends(require_feature("psa_integration"))` on PSA endpoints, Escalation Mode, Script Builder, Analytics endpoints. The 402-with-payload pattern lets the frontend route the user to `/account/billing/select-plan`.
+
+For quantitative limits (sessions per month, AI builds): existing `plan_limits` columns (`max_sessions_per_month`, `max_ai_builds_per_month`, etc.) already cover these. Use a sibling helper:
+
+```python
+async def require_within_limit(field: str):
+    """e.g., field='max_sessions_per_month' — checks current usage against
+    the resolved plan_limits value, with account-override consulting via
+    /admin/plan-limits/account-overrides table."""
+```
+
+This is closer to the existing `get_user_plan_limits` helper (`core/subscriptions.py`) and reuses that path.
+
+### Caching strategy
+
+- Subscription row, plan_limits row, plan_billing row, and resolved feature flag map: cached in `app.state.billing_cache` keyed by `account_id`. TTL 5 minutes.
+- Explicit invalidation triggers:
+  - Stripe webhook handler when `subscriptions` state changes (account-keyed invalidation).
+  - `/admin/plan-limits` PUT (invalidate **all** accounts on that plan, since plan-wide limits / billing fields changed).
+  - `/admin/plan-limits/account-overrides` POST/PUT/DELETE (account-keyed).
+  - `/admin/feature-flags` PUT/DELETE on flag definitions (full-cache flush).
+  - `/admin/feature-flags/plan-defaults` PUT (invalidate **all** accounts on that plan).
+  - `/admin/feature-flags/account-overrides` POST/DELETE (account-keyed).
+- For Railway multi-worker: per-process cache. The 5-minute TTL bounds inconsistency. Acceptable for v1; revisit with Redis pubsub if we run > 2 workers.
+
+### Frontend — `useBillingStore` + `GET /billing/state`
+
+```
+GET /billing/state -> {
+  subscription: {
+    status: 'trialing' | 'active' | 'past_due' | 'canceled' | 'incomplete' | 'complimentary',
+    plan: 'starter' | 'pro' | 'enterprise',
+    current_period_start: ISODateTime | null,
+    current_period_end: ISODateTime | null,
+    cancel_at_period_end: boolean,
+    seat_limit: number | null,
+    has_pro_entitlement: boolean,
+    is_paid: boolean,
+  },
+  plan_billing: {
+    display_name: string,
+    monthly_price_cents: number | null,
+    annual_price_cents: number | null,
+  },
+  plan_limits: {
+    max_trees, max_sessions_per_month, max_users, ...all current PlanLimits fields
+  },
+  enabled_features: Record<string, boolean>,  -- flat resolved map
+}
+```
+
+Frontend hooks:
+
+- `useFeature(key: string): boolean` — reads `enabled_features[key]` from `useBillingStore`.
+- `useFeatureLimit(key): { used, limit, percentage, isAtLimit }` — combines `plan_limits[key]` with a lazy `/usage/{key}` count.
+- `useTrialBanner(): { stage: 'pristine' | 'warning' | 'urgent' | 'expired', daysRemaining }` — derived from `subscription.status` + `current_period_end`.
+- `<FeatureGate feature="psa_integration" fallback={<UpgradePrompt />}>...children</FeatureGate>` — wrapper for whole-section gating.
+
+`useBillingStore` is a Zustand store with:
+- Initial fetch on auth-store login.
+- Refetch on webhook-driven server-sent events (or, for v1, polling every 60s while the dashboard is mounted).
+- Manual `refetchBilling()` exposed for use after Stripe Checkout success-redirect.
+
+`/auth/me` and `UserResponse` stay user-focused — no billing data embedded.
+
+### Admin UI — reuse existing surfaces
+
+- `/admin/plan-limits` — extended to also surface `plan_billing` fields in the editor (single PUT round-trips both tables in one transaction).
+- `/admin/feature-flags` — unchanged. Toggling a flag's `plan_feature_defaults` enables/disables the feature for that plan tier.
+- `/admin/feature-flags/account-overrides` — unchanged. Used for sales-negotiated grants, comp accounts, kill-switching a feature for one customer.
+
+No new combined `/admin/plans` admin page in v1.
+
+### Failure modes
+
+| Scenario | Outcome |
+|---|---|
+| User abandons Stripe Checkout | No webhook fires; `subscriptions.status` stays `trialing`; trial-end wall fires normally on day 14 via `require_active_subscription` |
+| Webhook arrives before app reconciles local state | `stripe_events` idempotency makes this safe |
+| Webhook secret rotated | Old webhook attempts 400 until env var redeployed |
+| Concurrent webhooks for the same subscription | DB row-level locks on the `subscriptions` row serialize updates; idempotency check is the first read in the transaction |
+| Stripe outage during checkout | `BillingService.create_checkout_session` raises; frontend shows "Couldn't start checkout — try again" toast |
+| Account on `complimentary` accidentally hits a webhook (e.g., admin manually attached a Stripe customer) | Handler transitions to whatever Stripe says; admin can revert via DB or via `/admin/plan-limits/account-overrides` if needed |
+| OAuth-only user attempts `/auth/login` (password) | Login endpoint rejects with 400 `{"error": "use_oauth_provider", "providers": ["google"]}` so frontend can route them to the right button |
+| OAuth-only user attempts `/auth/password/change` | Endpoint rejects with 400 — must set initial password via a separate `/auth/password/set-initial` flow (out of scope for v1; OAuth users stay OAuth-only) |
+| OAuth-only user requests password reset | Reset email is suppressed; user is shown "Sign in with {provider}" instead |
+
+---
+
+## Section 5 — Migration plan
+
+### Pre-deploy: Stripe configuration
+
+Manual setup, separate per environment.
+
+**Status note (2026-05-05):** Stripe **test mode** Products + Prices + webhook endpoint + test env vars in Railway are already configured. Live-mode setup remains for cutover.
+
+For each environment:
+
+1. **Stripe Dashboard**:
+   - Create Products: `ResolutionFlow Starter`, `ResolutionFlow Pro`, `ResolutionFlow Enterprise` (no public price).
+   - Create Prices for Starter/Pro: monthly + annual recurring.
+   - Enable **Customer Portal** with: update payment method, cancel subscription, view invoices. Disable plan-switching from the portal.
+   - Register webhook endpoint at `https://api.resolutionflow.com/api/v1/webhooks/stripe` with the events listed in Section 4. Save the signing secret.
+2. **Railway env vars** (per environment):
+   - `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`, `STRIPE_PUBLISHABLE_KEY` (frontend; needs `ARG`+`ENV` in `frontend/Dockerfile` per Lesson 60).
+
+### Schema migration
+
+Manual revisions per Lesson 77. New chain branches from the most recent of `main`'s heads (`070`, `c0f3a4b7e91d`, `024`) and merges via `alembic upgrade heads`. Migration filenames are listed in Section 2.
+
+Forward-only.
+
+### Pilot user transition
+
+- Migration step 8 sets `subscriptions.status='complimentary'`, `plan='pro'` for all existing accounts (≤ 100 rows). Single statement.
+- **Outbound communication**: a single email from `EmailService.send_complimentary_account_announcement` to every pilot user 1-2 days before cutover:
+  > *"We're opening ResolutionFlow up for new signups. Your account is now a Complimentary Pro account — nothing changes for you. You'll see a small "Complimentary Pro" tag in the app instead of any trial pill. Thanks for piloting."*
+- **In-app first-login toast** (optional; ship without if scope tightens): per-browser via localStorage key `rf-complimentary-announcement-seen-{user_id}`.
+
+### Existing invite-code disposition
+
+- `invite_codes` table preserved.
+- `User.invite_code_id` foreign keys preserved for historical pilots.
+- Registration handler (`/auth/register`) drops the invite_code-required gate. The `UserCreate.invite_code` field stays in the schema for backward compatibility but is ignored at registration. No new validations against the `invite_codes` table at signup.
+- No promo-code repurposing. Invite codes simply stop being consumed.
+
+### Beta-signup deprecation
+
+- `beta_signup.py` endpoint stays mounted but returns 307 redirect to `/register?from=beta`.
+- Existing waitlist rows: send a "we've launched — come on in" email with a one-time `from=beta` link. Preserve the table; do not drop.
+
+### Deploy ordering — dark launch then cutover
+
+1. **Backend deploy with `SELF_SERVE_ENABLED=false`**: all new endpoints exist (webhook handler, billing, OAuth callbacks, sales-leads, bulk invite, billing/state). `/auth/register` retains the existing invite-code requirement. `/pricing` returns 404. Webhook handler is **live**.
+2. **Frontend deploy with `VITE_SELF_SERVE_ENABLED=false`**: new surfaces are routed but hidden behind the flag.
+3. **Stripe live-mode configuration in prod** (manual, ~30 min).
+4. **Internal validation (1-2 days)**: founder + any teammates use a per-email allowlist to enable self-serve for their accounts only. Tests cover: email signup, OAuth signup paths, invitation accept (with email-match enforcement), pilot complimentary view, past-due simulation via Stripe test cards, subscription guard for locked accounts.
+5. **Cutover**: flip `SELF_SERVE_ENABLED=true` and `VITE_SELF_SERVE_ENABLED=true` in prod. Pricing page goes live.
+6. **Week 1 monitoring**: PostHog funnel; webhook logs; error rates.
+
+### Rollback strategy
+
+- Schema is forward-only — no down-migration for the backfills.
+- Rollback = flag flip. `SELF_SERVE_ENABLED=false` reverts public surfaces; pilot users continue on `complimentary` status (benign — the existing schema supports it either way after step 8).
+- New surfaces (pricing page, etc.) return 404 when the flag is off.
+- Webhook handler stays live regardless.
+
+### Risks worth flagging
+
+| Risk | Mitigation |
+|---|---|
+| Pilot users confused by "Complimentary Pro" change | Pre-launch email + first-login toast |
+| `is_paid` regression — paid metrics include comp accounts pre-fix | Audit `Subscription.is_paid` callers as part of step 1 of implementation; fix in same PR |
+| Webhook misfires producing wrong subscription state | Idempotency table + alerting + Stripe webhook replay |
+| Multi-head Alembic merge breaks in CI | Test `alembic upgrade heads` (plural) on a fresh DB before merging |
+| Stripe Test vs. Live mode confusion | Distinct env vars per env; first prod transaction verified manually |
+| OAuth callback `redirect_uri` drift across envs | Single `OAUTH_REDIRECT_BASE` env var; tested per env in validation |
+| Email deliverability for verification + invitations + sales leads | Reuse existing `EmailService` pipeline; verify SPF/DKIM/DMARC alignment |
+| Email-match enforcement at register breaks teammate accept if invitee mistypes their address | Clear error message; resend with corrected email is one click from the failure page |
+| Subscription guard allowlist drift (a new endpoint added without thinking about lockout) | Add a CI test that exercises every router with a `canceled` subscription and verifies 402 unless explicitly allowlisted |
+| Email-verification guard allowlist drift (a new endpoint added without thinking about unverified users past grace) | Same CI pattern — exercise every router with an unverified day-8 user and verify 403 unless explicitly allowlisted |
+| Plan key rename (`free`/`pro`/`team` → `starter`/`pro`/`enterprise`) | Decision deferred to implementation plan; if rename, migration must update every reference in `subscriptions.plan` and `plan_limits.plan` |
+
+---
+
+## Section 6 — Testing, rollout, open risks
+
+### Test strategy
+
+#### Backend (`pytest`)
+
+- **Unit tests** for `BillingService` methods. Stripe mocked via `respx`. Each method's happy path + at least one error path.
+- **Webhook handler integration tests**: feed canned Stripe webhook payloads and assert resulting `subscriptions` state. One test per event type. **Idempotency test**: send the same event id twice, assert single state mutation.
+- **`require_feature` integration tests**: parametrized over (plan, flag_key) pairs; test override resolution (`account_feature_overrides` beats `plan_feature_defaults`).
+- **`require_active_subscription` integration tests**:
+  - Each `subscriptions.status` value × allowlisted/non-allowlisted route → expected 200 or 402.
+  - **Replaces and verifies the trial expiry change**: a `trialing` row with `current_period_end < now()` should NOT be mutated by the dep; the dep should return 402 on protected routes and 200 on allowlisted routes.
+  - "complimentary should not block protected routes" smoke test.
+- **`require_verified_email_after_grace` integration tests**:
+  - Each combination of (verified, unverified-in-grace, unverified-past-grace) × (allowlisted, non-allowlisted route) → expected 200 or 403.
+  - OAuth-signup user has `email_verified_at` set at callback time → never blocked.
+  - User on day 6 unverified passes; user on day 8 unverified blocks; verifying mid-test transitions to passing.
+- **Combined-guard test**: protected routers mounting both `require_active_subscription` and `require_verified_email_after_grace` reject an unverified expired-trial account with the appropriate error (whichever check fires first is acceptable; assert one of the two error payloads).
+- **Subscription model property tests**: `is_active`, `is_paid`, `has_pro_entitlement` across every status × plan combination.
+- **Auth integration tests**:
+  - `/auth/register` happy path + duplicate email + weak password + email-match enforcement when `account_invite_code` provided.
+  - `/auth/google/callback` and `/auth/microsoft/callback` with mocked OAuth provider responses.
+  - `/auth/email/send-verification` auto-fired by register.
+  - `/auth/email/verify` with valid / expired / already-used tokens (already covered; smoke regression).
+  - **OAuth-only user paths**: `/auth/login` rejects, `/auth/password/change` rejects, password reset suppressed.
+- **Invitation tests**:
+  - `/accounts/me/invites` create now sends email (regression: today it doesn't).
+  - `/accounts/me/invites/bulk` creates N rows + sends N emails.
+  - Email-match enforcement at register.
+  - Expired/revoked token, idempotent re-accept.
+- **Plan-limits + feature-flags admin tests**: existing tests stay; extend with a test that round-trips `plan_billing` fields through `/admin/plan-limits` PUT.
+- **Anti-parrot guardrail**: existing `tests/test_prompt_anti_parrot.py` covers any new system prompts (verification email, invitation email, sales-lead intake) automatically.
+- **Phase 4 RLS smoke test**: every new account-scoped endpoint exercised with a non-matching `app.current_account_id`.
+
+#### Frontend (Vitest + Playwright)
+
+- **Component tests** for `<TrialPill />` (each subscription status branch + trialing-expired computed branch), `<NextStepCard />`, `<EmailVerificationBanner />`, `<EmailVerificationWall />`, `<TrialEndedWall />`, `<FeatureGate />`, `<UpgradePrompt />`.
+- **Hook tests** for `useFeature`, `useFeatureLimit`, `useTrialBanner`, `useBillingStore` (initial fetch, refetch on webhook event, refetch after Stripe Checkout success).
+- **Playwright E2E**:
+  - Register → wizard step-by-step → dashboard.
+  - OAuth round-trip with mocked provider.
+  - Trial-end wall → plan picker → mock Stripe Checkout → activated state.
+  - Past-due banner via webhook simulation.
+  - Pilot complimentary view (no walls, no nudges, "Complimentary Pro" pill).
+  - Invitation accept (full flow with `account_invite_code` from a backend fixture; email-match success and failure paths).
+
+#### Manual validation phase (1-2 days before cutover)
+
+| Scenario | Method |
+|---|---|
+| Email signup → wizard → first session → trial-end synthetic time → Checkout → active | Real flow with Stripe test mode + a date-shimmed account |
+| Google sign-in | Real Google account |
+| Microsoft sign-in | Real Microsoft 365 account |
+| Past-due simulation | Stripe test card `4000 0000 0000 0341` |
+| Pilot complimentary banner + first-login toast | Log in as an existing pilot account post-deploy |
+| Webhook signature mismatch handling | Send a forged webhook with bad signature, expect 400 + log entry |
+| OAuth provider redirect_uri matches | Visual check on each environment's Google + Microsoft app config |
+| `is_paid` audit | Query a known complimentary account: confirm `is_paid=False`, `has_pro_entitlement=True` |
+
+### Rollout monitoring
+
+#### PostHog event taxonomy
+
+- **Funnel**: `pricing_page_viewed`, `register_started`, `register_completed` (with `method`), `email_verification_sent`, `email_verification_completed`.
+- **Wizard**: `welcome_wizard_step_completed` (step number), `welcome_wizard_skipped` (`from_step`), `welcome_wizard_completed`.
+- **Activation**: `first_session_started` (existing), `psa_connected`, `teammate_invited`, `teammate_accepted_invite`.
+- **Trial conversion**: `trial_modal_shown`, `trial_modal_dismissed`, `trial_ended_wall_shown`, `plan_picker_viewed`, `checkout_session_created`, `checkout_completed`, `checkout_abandoned`.
+- **Feature-gate signal**: `feature_gate_blocked` (with `feature_key` + `current_plan`).
+- **Sales**: `talk_to_sales_form_submitted` (with `source`), `complimentary_account_first_view`.
+
+#### Alerting
+
+- Stripe webhook signature failures > 1/hour.
+- Stripe API errors during checkout-session creation > 1/hour.
+- OAuth callback failures > 5/hour.
+- Email send failures (`EmailService` errors) on verification or invitation paths.
+- Any 500 from `/webhooks/stripe`.
+- 402 rate spike on non-allowlisted endpoints (could indicate guard misconfiguration).
+
+#### Operational dashboards
+
+- Daily: trial signups, completed checkouts, MRR delta (using corrected `is_paid`).
+- Weekly: trial→paid conversion rate, OAuth-method mix, wizard skip rate per step.
+- Per-feature: `feature_gate_blocked` count by `flag_key`.
+
+### Stripe MCP tooling note
+
+Once the Stripe MCP plugin loads in a future Claude Code session, it speeds up two things: **debugging webhook state** for support cases and **ad-hoc subscription mutations** (compt'ing accounts, fixing stuck states). Worth using post-launch for ad-hoc support; not load-bearing for the spec.
+
+### Open risks and unknowns (carry-forward)
+
+| # | Item | Status |
+|---|---|---|
+| 1 | **Pricing numbers** ($/seat/month for Starter and Pro) | Out of design scope. Set during validation phase. Schema supports any value via `plan_billing.monthly_price_cents` / `annual_price_cents`. |
+| 2 | **Stripe Tax** | Disabled in v1. Revisit when first international signup arrives. |
+| 3 | **Multi-account membership** (one user in multiple shops) | Out of scope. v1 is one user → one account. |
+| 4 | **Owner transfer** | **Existing capability** — `POST /accounts/me/transfer-ownership` (`accounts.py:150`). Surface in the redesigned Account → Team page. |
+| 5 | **Annual billing UI** | Stripe Prices exist via `plan_billing.stripe_annual_price_id`, but the in-app picker only surfaces monthly in v1. Add later. |
+| 6 | **SSO (SAML/OIDC) for Enterprise** | Promised on the pricing page Enterprise tier. Actual impl deferred until first paying Enterprise customer. Sales conversation must set expectations honestly. |
+| 7 | **GDPR DPA template** | Trust strip claims "GDPR-ready DPA available." Founder/lawyer needs to produce the actual document — not eng work, but blocking the trust-strip claim being honest. |
+| 7b | **SOC2 status** | Trust strip claims "SOC2 in progress." If the engagement isn't started by cutover, soften the trust-strip copy. |
+| 8 | **Customer Portal cancellation customization** | Stripe-hosted Portal can't be customized. Acceptable for v1. |
+| 9 | **Email deliverability** | First big surge may trip spam filters. Verify SPF/DKIM/DMARC alignment before cutover. |
+| 10 | **Reverse-trial conversion math** | If trial→paid is bad post-launch, may need to flip to card-upfront. Schema supports it; policy decision based on data. Re-evaluate at week 4. |
+| 11 | **Promo codes** | **Deferred from v1.** No `promo_codes` table. If a launch campaign needs them, add a separate table later with Stripe coupon semantics; do not retrofit `invite_codes`. |
+| 12 | **Pricing page A/B testing** | Not in v1. PostHog has experiment tooling for A/B headlines later. |
+| 13 | **OAuth-only password set-initial flow** | An OAuth-only user can't add a password later in v1. Out of scope; users who want a password can ask support to enable it manually. |
+| 14 | **Plan key rename** | Existing `plan_limits` rows use `'free' / 'pro' / 'team'`. Public-facing tiers are Starter / Pro / Enterprise. Implementation plan decides whether to rename keys or maintain a display-name mapping in `plan_billing`. |
+
+---
+
+## Appendix A — Endpoint inventory
+
+Categorized as **NEW**, **MODIFIED**, or **EXISTING (referenced)**.
+
+### Public
+
+| Status | Method | Path | Purpose |
+|---|---|---|---|
+| NEW (frontend route) | GET | `/pricing` | Public pricing page |
+| NEW | POST | `/sales-leads` | Talk-to-sales form |
+| NEW | GET/POST | `/auth/google/callback` | Google OAuth callback |
+| NEW | GET/POST | `/auth/microsoft/callback` | Microsoft OAuth callback |
+| EXISTING | POST | `/auth/email/send-verification` | (auto-called from register; today user-initiated) |
+| EXISTING | POST | `/auth/email/verify` | Token consumption |
+| MODIFIED | POST | `/auth/register` | Drops invite-code-required gate; calls `BillingService.start_trial()`; auto-sends verification email; **enforces email match against `account_invites.email` when `account_invite_code` is provided** |
+| MODIFIED | POST | `/webhooks/stripe` | Stripe webhook handler. Stub exists at `app/api/endpoints/webhooks.py` (signature verification + early-out when `stripe_enabled=False`). This work fleshes out event handlers (`checkout.session.completed`, `customer.subscription.*`, `invoice.payment_*`), idempotency via `stripe_events`, and `BillingService.apply_subscription_event` integration. |
+
+### Authenticated user
+
+| Status | Method | Path | Purpose |
+|---|---|---|---|
+| EXISTING | GET | `/auth/me` | Stays user-focused — no billing data embedded |
+| NEW | GET | `/billing/state` | Subscription + plan + plan_limits + resolved feature flags |
+| NEW | POST | `/billing/checkout-session` | Create Stripe Checkout session |
+| NEW | GET | `/billing/portal-session` | Create Stripe Customer Portal session |
+| NEW | GET | `/usage/{flag_or_limit_key}` | Live usage count for quantitative limits |
+| NEW | PATCH | `/users/me/onboarding-step` | Persist welcome wizard step state (writes `accounts.name`, `accounts.team_size_bucket`, `accounts.primary_psa`, `users.role_at_signup`) |
+| EXISTING | POST | `/accounts/me/transfer-ownership` | Owner transfer (no change) |
+| MODIFIED | POST | `/accounts/me/invites` | **Now sends invite email at create-time** (today only resend sends) |
+| NEW | POST | `/accounts/me/invites/bulk` | Wraps single-create in a loop; sends email per row |
+| EXISTING | POST | `/accounts/me/invites/{id}/resend` | (no change) |
+| NEW | DELETE | `/accounts/me/invites/{id}` | Soft-revoke an invite by setting `revoked_at`. (No DELETE/revoke route exists today; only POST create, POST resend, GET list.) |
+
+### Super-admin (existing — referenced)
+
+| Status | Method | Path | Purpose |
+|---|---|---|---|
+| MODIFIED | GET | `/admin/plan-limits` | Response now includes `plan_billing` fields per row |
+| MODIFIED | PUT | `/admin/plan-limits` | Accepts `plan_billing` fields in payload (single transaction) |
+| EXISTING | GET/POST/PUT/DELETE | `/admin/plan-limits/account-overrides` | (no change) |
+| EXISTING | GET/POST/PUT/DELETE | `/admin/feature-flags` | (no change) |
+| EXISTING | PUT | `/admin/feature-flags/plan-defaults` | (no change) |
+| EXISTING | GET/POST/DELETE | `/admin/feature-flags/account-overrides` | (no change) |
+
+No new combined `/admin/plans` admin page in v1.
+
+---
+
+## Appendix B — Glossary
+
+- **Reverse trial**: time-bounded full-access trial with no card required at signup; card requested before billing kicks in.
+- **Sales-assist (E)**: dedicated path for Enterprise prospects via "Talk to sales" CTA → contact form → manual onboarding by founder/sales.
+- **Wedge**: Escalation Mode — the magic-moment feature pilots are evaluated against (≥1.0 hour saved per week per pilot per kill-switch criteria).
+- **Complimentary**: permanent, non-time-bounded `subscriptions.status='complimentary'` value for grandfathered pilot users. No nags, no walls, full Pro entitlement. Distinct from `trialing` in that it never expires; distinct from `active` in that it doesn't count toward paid/MRR metrics.
+- **Has Pro entitlement**: a property derived from `(status, plan, current_period_end)` that answers "can this account access Pro features right now?" — true for paid Pro, complimentary Pro, and active trials. Used by `require_feature` and `require_active_subscription`.
+- **Locked subscription**: computed state `(status='trialing' AND current_period_end < now())` OR `(status IN ('canceled', 'incomplete'))`. No mutation occurs; `require_active_subscription` raises 402 on protected routes.
+- **Plan keys**: `plan_limits.plan` is the canonical key; `plan_billing` joins on it; `subscriptions.plan` is the per-account key. Public-facing tier names (Starter / Pro / Enterprise) are display labels via `plan_billing.display_name`.

frontend/e2e/assistant-chat-prefill.spec.ts

@@ -0,0 +1,111 @@
+import { expect, test } from '@playwright/test'
+
+/**
+ * Regression test for the prefill-handoff `currentChatRef` bug.
+ *
+ * Symptom: a chat session created via the dashboard prefill flow
+ * looked fine on the first AI turn, but submitting partial answers
+ * from the task lane silently dropped the AI's follow-up response.
+ * The user saw their answers in the chat, no assistant reply, no
+ * toast.
+ *
+ * Root cause: the prefill effect in `AssistantChatPage` set
+ * `activeChatId` without also updating `currentChatRef.current`, so
+ * the `currentChatRef.current !== sentForChatId` guard in
+ * `handleTaskSubmit` (and `handleSend`) tripped on every subsequent
+ * request and discarded the AI response.
+ *
+ * Strategy: drive the real prefill flow against the real backend, but
+ * intercept the `/chat` endpoint with `page.route` so we get
+ * deterministic question payloads on turn 1 and a deterministic
+ * follow-up on turn 2. The fix is what makes turn 2 visible.
+ */
+test.describe('AssistantChatPage — prefill handoff regression', () => {
+  test('AI follow-up renders after submitting partial task lane answers', async ({ page }) => {
+    let chatCallCount = 0
+
+    // Clear any persisted active-chat-id so the page does not auto-resume a
+    // stale session left behind by a sibling spec.
+    await page.addInitScript(() => {
+      try {
+        sessionStorage.removeItem('rf-active-chat-id')
+        sessionStorage.removeItem('rf-tasklane-meta')
+      } catch { /* ignore */ }
+    })
+
+    // Intercept only the chat endpoint. Session creation, listSessions,
+    // facts, suggested-fixes, etc. all hit the real backend so the page
+    // renders normally — only the LLM call is deterministic. The pattern
+    // matches `/ai-sessions/<uuid>/chat` and nothing nested beneath it.
+    await page.route(/\/api\/v1\/ai-sessions\/[^/]+\/chat$/, async (route) => {
+      if (route.request().method() !== 'POST') {
+        await route.fallback()
+        return
+      }
+      chatCallCount += 1
+      if (chatCallCount === 1) {
+        await route.fulfill({
+          status: 200,
+          contentType: 'application/json',
+          body: JSON.stringify({
+            content: 'Initial diagnostic plan. Please answer the questions in the task lane.',
+            suggested_flows: [],
+            fork: null,
+            actions: [],
+            questions: [
+              { text: 'Has the user recently changed their password?' },
+              { text: 'Is the lockout happening at a consistent time of day?' },
+            ],
+          }),
+        })
+        return
+      }
+      await route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          content: 'Got it — based on your answer, here is what to check next.',
+          suggested_flows: [],
+          fork: null,
+          actions: [],
+          questions: [],
+        }),
+      })
+    })
+
+    // Drive the prefill flow exactly the way the dashboard does. The textarea
+    // is keyed by its placeholder copy on QuickStartPage.
+    await page.goto('/')
+    const prefillBox = page.getByPlaceholder(/Describe the issue/i)
+    await expect(prefillBox).toBeVisible({ timeout: 10_000 })
+    await prefillBox.fill('User locked out of AD weekly')
+    await prefillBox.press('Enter')
+
+    // After the prefill submits we land on /pilot and the first stubbed AI
+    // turn surfaces the task-lane question text.
+    await expect(page).toHaveURL(/\/pilot/)
+    await expect(
+      page.getByText('Has the user recently changed their password?'),
+    ).toBeVisible({ timeout: 15_000 })
+
+    // Answer the first question. UI flow: click "Answer" to open the
+    // textarea, type, click the inline "Answer" button to mark done.
+    await page.getByRole('button', { name: /^Answer$/ }).first().click()
+    await page.getByPlaceholder('Type your answer...').fill('No, password is months old')
+    await page.getByRole('button', { name: /^Answer$/ }).first().click()
+
+    // Submit the partial response. Pre-fix: the response was silently dropped
+    // here because `currentChatRef.current` still held the mount-time value.
+    await page.getByRole('button', { name: /Send 1 of 2 Responses/ }).click()
+
+    // Bug repro: the assistant message must render. Pre-fix this assertion
+    // fails because `handleTaskSubmit` early-returns at the
+    // `currentChatRef.current !== sentForChatId` guard.
+    await expect(
+      page.getByText('Got it — based on your answer, here is what to check next.'),
+    ).toBeVisible({ timeout: 15_000 })
+
+    // Both chat calls must have actually happened.
+    expect(chatCallCount).toBe(2)
+  })
+})

frontend/e2e/history.spec.ts

@@ -34,7 +34,11 @@ test.describe('session history smoke tests', () => {
       await page.getByPlaceholder('Search by ticket number...').fill(ticketNumber)
       await page.getByPlaceholder('Search by client name...').fill(clientName)
 
-      const sessionCard = page.locator('.bg-card').filter({ hasText: ticketNumber }).filter({ hasText: clientName }).first()
+      const sessionCard = page
+        .getByTestId('flow-session-card')
+        .filter({ hasText: ticketNumber })
+        .filter({ hasText: clientName })
+        .first()
       await expect(sessionCard).toBeVisible()
       await expect(sessionCard.getByText(tree.name)).toBeVisible()
 

frontend/e2e/library-start.spec.ts

@@ -24,7 +24,7 @@ test.describe('flow library start-session smoke tests', () => {
       await page.getByPlaceholder('Search flows...').fill(tree.name)
       await page.getByRole('button', { name: 'Search', exact: true }).click()
 
-      const treeCard = page.locator('.bg-card').filter({ hasText: tree.name }).first()
+      const treeCard = page.getByTestId('tree-card').filter({ hasText: tree.name }).first()
       await expect(treeCard).toBeVisible()
       await treeCard.getByRole('button', { name: /^Start(?: Session)?$/ }).click()
 

frontend/e2e/library.spec.ts

@@ -20,7 +20,7 @@ test.describe('flow library smoke tests', () => {
       await page.getByPlaceholder('Search flows...').fill(tree.name)
       await page.getByRole('button', { name: 'Search', exact: true }).click()
 
-      await expect(page.getByText(tree.name)).toBeVisible()
+      await expect(page.getByTestId('tree-card').filter({ hasText: tree.name }).first()).toBeVisible()
     } finally {
       await disposeApiContext(api)
     }

frontend/e2e/navigation.spec.ts

@@ -30,7 +30,7 @@ test.describe('authenticated navigation smoke tests', () => {
     await page.goto('/account')
 
     await expect(
-      page.getByRole('heading', { name: 'Account Management' }),
+      page.getByRole('heading', { name: 'Settings' }),
     ).toBeVisible()
   })
 })

frontend/e2e/resume.spec.ts

@@ -28,7 +28,7 @@ test.describe('session resume smoke tests', () => {
       await page.getByRole('button', { name: 'Flow Sessions' }).click()
       // Active sub-tab is the default and surfaces in-progress sessions.
 
-      const resumeCard = page.locator('.bg-card').filter({ hasText: tree.name }).first()
+      const resumeCard = page.getByTestId('flow-session-card').filter({ hasText: tree.name }).first()
       await expect(resumeCard).toBeVisible()
       await resumeCard.getByRole('button', { name: 'Resume' }).first().click()
 

frontend/e2e/shares.spec.ts

@@ -31,7 +31,7 @@ test.describe('shared session management smoke tests', () => {
       ).toBeVisible()
       await expect(page.getByText(share.share_name || '')).toBeVisible()
 
-      const shareCard = page.locator('.bg-card').filter({ hasText: share.share_name || '' }).first()
+      const shareCard = page.getByTestId('share-card').filter({ hasText: share.share_name || '' }).first()
       await shareCard.getByRole('button', { name: 'Revoke' }).click()
 
       const confirmDialog = page.getByRole('dialog', { name: 'Revoke Share Link' })

frontend/src/App.tsx

@@ -16,7 +16,7 @@ function App() {
     } else {
       setLoading(false)
     }
-  }, [])
+  }, [fetchUser, isAuthenticated, setLoading])
 
   return <RouterProvider router={router} />
 }