Upload 5 files

README.md

@@ -34,9 +34,10 @@ helps the patient articulate their own values and concerns.
 
 ## Saving and resuming sessions (Supabase)
 
-Participants are identified by their email address. Everything they do is saved
-against that address, so closing the page and returning later — even on another
-device — picks up exactly where they left off.
+Participants sign in with a **User ID** and an **email address**. Everything they
+do is saved against that email, so closing the page and returning later — even on
+another device — picks up exactly where they left off. The User ID is checked on
+every return visit, so entering someone else's email does not open their session.
 
 ### One-time setup
 
@@ -72,9 +73,9 @@ and it will not overwrite anything already stored for them.
 
 ### What gets stored
 
-`p3_sessions` — one resumable row per email: the 16 answers, the conversation
-the participant sees, the full model-facing conversation, and the follow-up
-counter.
+`p3_sessions` — one resumable row per email: the participant's User ID, the 16
+answers, the conversation they see, the full model-facing conversation, and the
+follow-up counter.
 
 `p3_messages` — an append-only log of every turn. Session rows are replaced when
 a participant starts over; this log never is, so no transcript is lost.
@@ -84,16 +85,33 @@ in the Table Editor.
 
 ### What participants see
 
-- They are asked for their email before anything else.
-- A returning participant with a saved conversation is taken straight back into
-  it; **Review or change my answers** shows their restored questionnaire.
+- They are asked for their **User ID first, then their email address**, before
+  anything else. Both are stored in Supabase.
+- Their User ID is shown in the **top right of the page** for as long as they are
+  signed in, so they can note it for next time.
+- If a returning participant enters the wrong User ID for an email, they are
+  refused. The **second** wrong attempt tells them the User ID is displayed at
+  the top right of the page.
+- The conversation **opens with all 16 questions and their own answers**, so the
+  profile the follow-up is built on is visible without leaving the chat.
 - The questionnaire auto-saves as it is filled in, so a half-finished intake
   survives a closed tab.
-- **Start Over** clears both the page and the stored session (the transcript log
-  is kept). **Use a different email** just signs out; nothing is deleted.
+- **Start Over** first shows a warning that it erases the current chat history and
+  starts a new session, and only erases anything once confirmed. The transcript
+  log in `p3_messages` is kept either way. **Use a different email** just signs
+  out; nothing is deleted.
 - If the same session is open in two places, the older one is told to reload
   rather than being allowed to overwrite the newer conversation.
 
+### Changing a participant's User ID
+
+```sql
+update public.p3_sessions set user_id = 'P3-NEW' where email = 'someone@example.com';
+```
+
+A row created before User IDs existed has none stored; the first sign-in after
+that adopts whatever User ID is entered, and it is enforced from then on.
+
 ### Deleting a participant's data
 
 ```sql

app.py

@@ -20,6 +20,7 @@ Deploy on Hugging Face Spaces (SDK: Gradio).
 
 import os
 import json
+import html
 
 # ----------------------------------------------------------------------
 # ZeroGPU compatibility shim (harmless on CPU basic; skipped if not present).
@@ -41,7 +42,8 @@ import gradio as gr
 
 from knowledge_base import KnowledgeBase
 from supabase_store import (SupabaseStore, normalize_email, is_valid_email,
-                            CONFLICT)
+                            normalize_user_id, is_valid_user_id,
+                            user_ids_match, CONFLICT)
 
 # ----------------------------------------------------------------------
 # The 16 profile questions (verbatim from the intake form)
@@ -225,27 +227,59 @@ def _status_line(email, saving, restored=False):
     return f"Signed in as **{email}**. {note}"
 
 
-def _gate_view(email, panel, status, radio_updates, chat_display=None,
-               convo=None, n_followups=0, can_save=True, revision=0):
+def _user_badge(user_id):
+    """The User ID shown in the top-right corner while signed in.
+
+    The sign-in error message points participants here, so this has to be
+    present on every screen after sign-in.
+    """
+    if not user_id:
+        return ""
+    # is_valid_user_id already rejects angle brackets and ampersands, but the
+    # badge is rendered as HTML, so escape anyway rather than depend on that.
+    return f"User ID<br><strong>{html.escape(user_id)}</strong>"
+
+
+ANSWERS_SUMMARY_HEADING = "**Your responses to the 16 questions**"
+
+
+def build_answers_summary(answers):
+    """The 16 questions and this participant's answers, shown as the opening
+    message of the chat so they can see the profile the conversation is built
+    on without leaving the conversation."""
+    lines = [ANSWERS_SUMMARY_HEADING, ""]
+    for i, (question, answer) in enumerate(zip(QUESTIONS, answers), start=1):
+        shown = answer if answer in ("Yes", "No") else "Not answered"
+        lines.append(f"{i}. **{shown}** — {question}")
+    return "\n".join(lines)
+
+
+def _gate_view(user_id, email, panel, status, radio_updates, chat_display=None,
+               convo=None, n_followups=0, can_save=True, revision=0,
+               uid_attempts=0):
     """Build the output tuple shared by every sign-in outcome."""
     chat_display = chat_display or []
     convo = convo or []
     return (
-        email,
+        user_id,                                        # user_id_state
+        email,                                          # email_state
         chat_display,                                   # chatbot
         chat_display,                                   # display_state
         convo,                                          # convo_state
         n_followups,
         can_save,                                       # can_save state
         revision,                                       # revision state
+        uid_attempts,                                   # uid_attempts state
+        gr.update(value=_user_badge(user_id)),          # user_badge
         gr.update(visible=(panel == "email")),          # email_panel
         gr.update(visible=(panel == "intake")),         # intake_panel
         gr.update(visible=(panel == "chat")),           # chat_panel
         gr.update(value=status),                        # status_md
         gr.update(visible=(panel != "email")),          # switch_btn
-        gr.update(visible=False),                       # back_btn (review only)
         gr.update(value=""),                            # msg — never carry a
                                                         # draft across sign-ins
+        gr.update(visible=False),                       # reset_confirm
+        gr.update(visible=True),                        # restart_btn
         *radio_updates,
     )
 
@@ -376,6 +410,36 @@ def _latest_user_query(convo):
     return ""
 
 
+def _empty_reply_reason(resp):
+    """Why the model returned nothing, e.g. ' (stopped early: RECITATION)'.
+
+    Best effort and never raises: it only exists to make the warning the
+    participant sees, and the Space logs, more diagnosable.
+    """
+    def _name(value):
+        return (getattr(value, "name", None) or str(value or "")).strip()
+
+    try:
+        blocked = _name(getattr(getattr(resp, "prompt_feedback", None),
+                                "block_reason", None))
+        # google-genai spells it BLOCKED_REASON_UNSPECIFIED; the older
+        # generativelanguage SDK spelled it BLOCK_REASON_UNSPECIFIED. Accept
+        # both so the "no real reason given" case always falls through to the
+        # finish_reason below rather than being reported as a block.
+        if blocked and blocked.upper() not in (
+                "BLOCKED_REASON_UNSPECIFIED", "BLOCK_REASON_UNSPECIFIED", "NONE"):
+            return f" (the question was blocked: {blocked})"
+    except Exception:
+        pass
+    try:
+        reason = _name(resp.candidates[0].finish_reason)
+        if reason and reason.upper() not in ("STOP", "FINISH_REASON_UNSPECIFIED"):
+            return f" (stopped early: {reason})"
+    except Exception:
+        pass
+    return ""
+
+
 def gemini_reply(client, convo, n_followups):
     """convo: internal history list. Retrieves KB context for the latest user
     turn and injects it, then asks Gemini to answer grounded in that context."""
@@ -426,26 +490,52 @@ def gemini_reply(client, convo, n_followups):
         thinking_config=types.ThinkingConfig(thinking_budget=0),
     )
     resp = client.models.generate_content(model=MODEL, contents=contents, config=cfg)
-    return (resp.text or "").strip()
+    text = (resp.text or "").strip()
+    if not text:
+        # A response with no text part — a safety or recitation block, or a
+        # truncated candidate. `resp.text` is None here and the SDK does not
+        # raise, so without this the empty string would be committed as a blank
+        # assistant bubble and written to Supabase. Raise instead, so the
+        # callers' existing error handling rolls the turn back and tells the
+        # participant something went wrong.
+        raise RuntimeError(
+            "the model returned an empty response" + _empty_reply_reason(resp)
+            + ". Please rephrase your question and try again.")
+    return text
 
 
 # ----------------------------------------------------------------------
 # Gradio app
 # ----------------------------------------------------------------------
-def enter_email(email_raw):
-    """Sign in with an email address, restoring a previous session if one exists."""
+def sign_in(user_id_raw, email_raw, uid_attempts):
+    """Sign in with a User ID and email, restoring a previous session if one
+    exists. The User ID is checked against the one stored for that email, so a
+    participant cannot open someone else's session by guessing an address."""
+    user_id = normalize_user_id(user_id_raw)
     email = normalize_email(email_raw)
     blank_radios = [gr.update(value=None) for _ in QUESTIONS]
+    keep_radios = [gr.update() for _ in QUESTIONS]
+    try:
+        uid_attempts = int(uid_attempts or 0)
+    except (TypeError, ValueError):
+        uid_attempts = 0
+
+    if not is_valid_user_id(user_id):
+        gr.Warning("Please enter your User ID to begin.")
+        return _gate_view("", "", "email", "", keep_radios,
+                          uid_attempts=uid_attempts)
 
     if not is_valid_email(email):
         gr.Warning("Please enter a valid email address, for example name@example.com.")
-        return _gate_view("", "email", "", [gr.update() for _ in QUESTIONS])
+        return _gate_view("", "", "email", "", keep_radios,
+                          uid_attempts=uid_attempts)
 
     # Persistence not configured — the chatbot still works, it just won't save.
     if not STORE.enabled:
         gr.Warning(STORE.config_hint() + ". You can continue, but nothing will be saved.")
-        return _gate_view(email, "intake", _status_line(email, saving=False),
-                          blank_radios, can_save=False)
+        return _gate_view(user_id, email, "intake",
+                          _status_line(email, saving=False), blank_radios,
+                          can_save=False)
 
     row, err = STORE.load_session(email)
     if err:
@@ -453,25 +543,43 @@ def enter_email(email_raw):
         # a blank new session saved on top would destroy a real transcript.
         gr.Warning(f"Could not reach Supabase ({err}). You can continue, but "
                    "nothing from this visit will be saved.")
-        return _gate_view(email, "intake", _status_line(email, saving=False),
-                          blank_radios, can_save=False)
+        return _gate_view(user_id, email, "intake",
+                          _status_line(email, saving=False), blank_radios,
+                          can_save=False)
 
     # First time we've seen this address.
     if row is None:
-        created, err = STORE.ensure_session(email)
+        created, err = STORE.ensure_session(email, user_id=user_id)
         if err:
             # Without a row the questionnaire's auto-save has nothing to
             # update, so it would quietly do nothing while the status line
             # promised otherwise. Say so instead.
             gr.Warning(f"Could not start your session in Supabase ({err}). You "
                        "can continue, but nothing from this visit will be saved.")
-            return _gate_view(email, "intake", _status_line(email, saving=False),
-                              blank_radios, can_save=False)
+            return _gate_view(user_id, email, "intake",
+                              _status_line(email, saving=False), blank_radios,
+                              can_save=False)
         revision = int((created or {}).get("revision") or 0)
-        return _gate_view(email, "intake", _status_line(email, saving=True),
-                          blank_radios, revision=revision)
+        return _gate_view(user_id, email, "intake",
+                          _status_line(email, saving=True), blank_radios,
+                          revision=revision)
+
+    # Returning participant — the User ID has to match the stored one.
+    stored_uid = normalize_user_id(row.get("user_id"))
+    if stored_uid and not user_ids_match(stored_uid, user_id):
+        attempts = uid_attempts + 1
+        if attempts >= 2:
+            gr.Warning(
+                "That User ID still does not match the one saved for this email "
+                "address. Your User ID is displayed at the top right of the "
+                "page while you are signed in — please check it there and try "
+                "again."
+            )
+        else:
+            gr.Warning("That User ID does not match the one saved for this "
+                       "email address. Please check it and try again.")
+        return _gate_view("", "", "email", "", keep_radios, uid_attempts=attempts)
 
-    # Returning participant — restore whatever they had.
     answers = _coerce_answers(row.get("answers"))
     chat_display = _coerce_messages(row.get("chat_display"))
     convo = _coerce_messages(row.get("convo"))
@@ -485,64 +593,47 @@ def enter_email(email_raw):
         revision = 0
     radio_updates = [gr.update(value=a) for a in answers]
 
+    if not stored_uid:
+        # A row created before User IDs existed, or one whose sign-in never
+        # managed to write it. Adopt the ID they just gave us.
+        revision = _persist(email, True, revision, user_id=user_id)
+
+    # Show the User ID the way it is stored, so what the badge displays is the
+    # canonical study ID rather than whatever casing was typed this time.
+    display_uid = stored_uid or user_id
+
     if chat_display and convo:
+        # A conversation saved before the opening summary existed has none, so
+        # add it here: every chat should begin with the 16 questions.
+        if (any(a is not None for a in answers)
+                and not chat_display[0]["content"].startswith(ANSWERS_SUMMARY_HEADING)):
+            chat_display = [{"role": "assistant",
+                             "content": build_answers_summary(answers)}] + chat_display
         gr.Info("Welcome back — your answers and conversation have been restored.")
-        return _gate_view(email, "chat",
+        return _gate_view(display_uid, email, "chat",
                           _status_line(email, saving=True, restored=True), radio_updates,
                           chat_display=chat_display, convo=convo,
                           n_followups=n_followups, revision=revision)
 
     if any(a is not None for a in answers):
         gr.Info("Welcome back — your saved answers have been filled in.")
-        return _gate_view(email, "intake",
+        return _gate_view(display_uid, email, "intake",
                           _status_line(email, saving=True, restored=True),
                           radio_updates, revision=revision)
 
-    return _gate_view(email, "intake", _status_line(email, saving=True),
+    return _gate_view(display_uid, email, "intake", _status_line(email, saving=True),
                       blank_radios, revision=revision)
 
 
 def switch_email():
-    """Sign out: clear the in-page session and go back to the email screen.
+    """Sign out: clear the in-page session and go back to the sign-in screen.
 
     Nothing is deleted from Supabase — signing back in restores it.
     """
-    return _gate_view("", "email", "", [gr.update(value=None) for _ in QUESTIONS]) + (
-        gr.update(value=""),                            # clear the email textbox
-    )
-
-
-def review_answers(email, can_save, *current_values):
-    """Show the intake form again, prefilled, without disturbing the
-    conversation. Lets a returning participant actually see (and change) the
-    answers that were restored for them.
-
-    Starts from whatever is already on the form, so a failed (or disabled)
-    Supabase read reveals the questionnaire untouched instead of wiping it.
-    """
-    answers = [v if v in ("Yes", "No") else None for v in current_values]
-    if email and can_save and STORE.enabled:
-        row, err = STORE.load_session(email)
-        if err:
-            gr.Warning(f"Could not load your saved answers: {err}")
-        elif row:
-            stored = _coerce_answers(row.get("answers"))
-            if any(a is not None for a in stored):
-                answers = stored
-    return (
-        gr.update(visible=True),        # intake_panel
-        gr.update(visible=False),       # chat_panel
-        gr.update(visible=True),        # back_btn
-        *[gr.update(value=a) for a in answers],
-    )
-
-
-def back_to_chat():
-    """Return to the conversation, which was never cleared."""
-    return (
-        gr.update(visible=False),       # intake_panel
-        gr.update(visible=True),        # chat_panel
-        gr.update(visible=False),       # back_btn
+    return _gate_view("", "", "email", "",
+                      [gr.update(value=None) for _ in QUESTIONS]) + (
+        gr.update(value=""),                            # clear the User ID box
+        gr.update(value=""),                            # clear the email box
     )
 
 
@@ -562,11 +653,9 @@ def start_chat(api_key, email, can_save, revision, chat_display, convo,
         missing = [i + 1 for i, v in enumerate(answers) if v is None]
         gr.Warning(f"Please answer all 16 questions. Missing: {missing}")
         # Nothing has been written yet, so a rejected submission must change
-        # nothing: hand the existing conversation state straight back. (A
-        # participant can reach this from "Review or change my answers" with a
-        # live conversation open.)
+        # nothing: hand the existing conversation state straight back.
         return (gr.update(), chat_display, convo, n_followups, revision,
-                gr.update(visible=True), gr.update(visible=False), gr.update())
+                gr.update(visible=True), gr.update(visible=False))
 
     # Starting a follow-up replaces any previous conversation. Write the new
     # answers and the cleared conversation together, before the slow model
@@ -581,7 +670,7 @@ def start_chat(api_key, email, can_save, revision, chat_display, convo,
     if err:
         gr.Warning(err)
         return ([], [], [], 0, revision, gr.update(visible=True),
-                gr.update(visible=False), gr.update(visible=False))
+                gr.update(visible=False))
 
     # Build the knowledge base on first use (may take a bit on cold start).
     ready, msg = ensure_kb(client)
@@ -608,15 +697,25 @@ def start_chat(api_key, email, can_save, revision, chat_display, convo,
     except Exception as e:
         gr.Warning(f"Gemini error: {e}")
         return ([], [], [], 0, revision, gr.update(visible=True),
-                gr.update(visible=False), gr.update(visible=False))
+                gr.update(visible=False))
 
     convo.append({"role": "assistant", "content": reply})
-    chat_display = [{"role": "assistant", "content": reply}]
+    # The conversation opens with the participant's own answers, so the profile
+    # the follow-up is built on is visible without leaving the chat. It is part
+    # of chat_display (what they see) but not of convo (the model already has
+    # the profile in its hidden seed turn).
+    summary = build_answers_summary(answers)
+    chat_display = [
+        {"role": "assistant", "content": summary},
+        {"role": "assistant", "content": reply},
+    ]
 
     revision = _persist(email, can_save, revision, answers=answers, convo=convo,
                         chat_display=chat_display, followups=0)
-    _log_turns(email, can_save,
-               [{"role": "assistant", "content": reply, "turn": 0}])
+    _log_turns(email, can_save, [
+        {"role": "assistant", "content": summary, "turn": 0},
+        {"role": "assistant", "content": reply, "turn": 0},
+    ])
 
     return (
         chat_display,
@@ -626,20 +725,23 @@ def start_chat(api_key, email, can_save, revision, chat_display, convo,
         revision,
         gr.update(visible=False),       # intake_panel
         gr.update(visible=True),        # chat_panel
-        gr.update(visible=False),       # back_btn — this IS the conversation now
     )
 
 
 def respond(user_msg, chat_display, convo, n_followups, api_key, email,
             can_save, revision):
+    # Carrying on with the conversation means the participant is not starting
+    # over, so any pending confirmation is dismissed rather than left armed.
+    dismiss = (gr.update(visible=False), gr.update(visible=True))
     user_msg = (user_msg or "").strip()
     if not user_msg:
-        return chat_display, chat_display, convo, n_followups, revision, ""
+        return (chat_display, chat_display, convo, n_followups, revision, "") + dismiss
 
     client, err = get_client(api_key)
     if err:
         gr.Warning(err)
-        return chat_display, chat_display, convo, n_followups, revision, user_msg
+        return (chat_display, chat_display, convo, n_followups, revision,
+                user_msg) + dismiss
 
     ensure_kb(client)  # no-op if already built
 
@@ -650,7 +752,7 @@ def respond(user_msg, chat_display, convo, n_followups, api_key, email,
         reply = gemini_reply(client, convo, n_followups)
     except Exception as e:
         gr.Warning(f"Gemini error: {e}")
-        return chat_display, chat_display, convo, n_followups, revision, ""
+        return (chat_display, chat_display, convo, n_followups, revision, "") + dismiss
 
     convo = convo + [{"role": "assistant", "content": reply}]
 
@@ -671,13 +773,32 @@ def respond(user_msg, chat_display, convo, n_followups, api_key, email,
         {"role": "assistant", "content": display_reply, "turn": n_followups + 1},
     ])
 
-    return chat_display, chat_display, convo, n_followups + 1, revision, ""
+    return (chat_display, chat_display, convo, n_followups + 1, revision, "") + dismiss
+
+
+def show_reset_warning():
+    """Start Over is destructive, so it asks first."""
+    gr.Warning("Starting over will erase your current chat history and begin a "
+               "new session.")
+    return (
+        gr.update(visible=True),        # reset_confirm
+        gr.update(visible=False),       # restart_btn — replaced by the choice
+    )
+
+
+def cancel_reset():
+    """Back out of Start Over, leaving the conversation untouched."""
+    return (
+        gr.update(visible=False),       # reset_confirm
+        gr.update(visible=True),        # restart_btn
+    )
 
 
 def reset_all(email, can_save, revision):
-    """Start Over: clear this page AND the stored session, so a participant who
-    restarts and leaves is not dropped back into the conversation they
-    abandoned. The p3_messages transcript log is deliberately left intact."""
+    """Start Over, confirmed: clear this page AND the stored session, so a
+    participant who restarts and leaves is not dropped back into the
+    conversation they abandoned. The p3_messages transcript log is deliberately
+    left intact, so nothing is lost for the study."""
     revision = _persist(email, can_save, revision, answers=[None] * len(QUESTIONS),
                         convo=[], chat_display=[], followups=0)
     radio_resets = [gr.update(value=None) for _ in QUESTIONS]
@@ -689,8 +810,9 @@ def reset_all(email, can_save, revision):
         revision,
         gr.update(visible=True),        # intake_panel
         gr.update(visible=False),       # chat_panel
-        gr.update(visible=False),       # back_btn — there is no chat to go back to
         gr.update(value=""),            # msg — drop any unsent draft
+        gr.update(visible=False),       # reset_confirm
+        gr.update(visible=True),        # restart_btn
         *radio_resets,
     )
 
@@ -815,6 +937,43 @@ button.secondary, .gradio-container button.secondary {
     background: #ffffff !important;
     box-shadow: 0 1px 2px rgba(0,0,0,0.04) !important;
 }
+#app-header {
+    align-items: flex-start !important;
+}
+#user-id-badge {
+    text-align: right !important;
+    font-size: 0.85rem !important;
+    color: #5a5a5a !important;
+    line-height: 1.3 !important;
+}
+#user-id-badge p {
+    color: #5a5a5a !important;
+    margin: 0 !important;
+    text-align: right !important;
+}
+#user-id-badge strong {
+    color: #7a0c2e !important;
+    font-size: 1rem !important;
+    letter-spacing: 0.02em;
+}
+button.stop, .gradio-container button.stop {
+    background: #b3261e !important;
+    color: #ffffff !important;
+    border: none !important;
+    border-radius: 6px !important;
+    font-weight: 600 !important;
+}
+button.stop:hover, .gradio-container button.stop:hover {
+    background: #8c1d16 !important;
+}
+.reset-warning {
+    border: 1px solid #7a0c2e !important;
+    border-left: 4px solid #7a0c2e !important;
+    border-radius: 8px !important;
+    padding: 14px 16px !important;
+    margin-top: 8px !important;
+    background: #fdf6f8 !important;
+}
 footer {visibility: hidden;}
 """
 
@@ -824,10 +983,11 @@ with gr.Blocks(title="MyeAI (Myeloma AI)", css=CSS,
                    neutral_hue=gr.themes.colors.gray,
                    font=[gr.themes.GoogleFont("Inter"), "system-ui", "sans-serif"],
                )) as demo:
-    with gr.Column(elem_id="app-header"):
-        gr.HTML(
-            "<h1 id='app-title'>MyeAI (Myeloma AI)</h1>"
-        )
+    with gr.Row(elem_id="app-header"):
+        gr.HTML("<h1 id='app-title'>MyeAI (Myeloma AI)</h1>")
+        # The sign-in error for a wrong User ID points participants here, so it
+        # has to be visible on every screen once they are signed in.
+        user_badge = gr.Markdown("", elem_id="user-id-badge")
 
     api_key = gr.State("")
     convo_state = gr.State([])
@@ -841,6 +1001,10 @@ with gr.Blocks(title="MyeAI (Myeloma AI)", css=CSS,
     revision = gr.State(0)
     # Throttles the "your answers are not being saved" warning to once.
     answers_warned = gr.State(False)
+    user_id_state = gr.State("")
+    # Consecutive failed User ID attempts, so the second one can point the
+    # participant at where their User ID is shown.
+    uid_attempts = gr.State(0)
 
     status_md = gr.Markdown("", elem_id="status-line")
     switch_btn = gr.Button("Use a different email", size="sm",
@@ -848,17 +1012,18 @@ with gr.Blocks(title="MyeAI (Myeloma AI)", css=CSS,
 
     with gr.Group(visible=True, elem_classes="email-card") as email_panel:
         gr.Markdown(
-            "**Enter your email address to begin.**\n\n"
-            "Your answers and your conversation are saved against this address, so you "
+            "**Enter your User ID and email address to begin.**\n\n"
+            "Your answers and your conversation are saved against these, so you "
             "can close this page and come back later to pick up exactly where you left off."
         )
+        user_id_box = gr.Textbox(label="User ID", placeholder="e.g. P3-014",
+                                 max_lines=1, autofocus=True)
         email_box = gr.Textbox(label="Email address", placeholder="name@example.com",
-                               max_lines=1, autofocus=True)
+                               max_lines=1)
         email_btn = gr.Button("Continue", variant="primary")
 
     with gr.Group(visible=False) as intake_panel:
         gr.Markdown("**Answer all 16 questions, then click Start Follow-up.**")
-        back_btn = gr.Button("Back to my conversation", size="sm", visible=False)
         radios = []
         for i, q in enumerate(QUESTIONS):
             with gr.Row(elem_classes="q-card"):
@@ -877,21 +1042,32 @@ with gr.Blocks(title="MyeAI (Myeloma AI)", css=CSS,
         with gr.Row():
             msg = gr.Textbox(placeholder="Type or paste your question here...", show_label=False, scale=8)
             send_btn = gr.Button("Send", variant="primary", scale=1)
-        with gr.Row():
-            review_btn = gr.Button("Review or change my answers")
-            restart_btn = gr.Button("Start Over")
+        restart_btn = gr.Button("Start Over")
+        with gr.Group(visible=False, elem_classes="reset-warning") as reset_confirm:
+            gr.Markdown(
+                "**Are you sure you want to start over?**\n\n"
+                "This erases your current chat history and begins a new session. "
+                "You will answer the 16 questions again."
+            )
+            with gr.Row():
+                confirm_reset_btn = gr.Button("Yes, erase and start over",
+                                              variant="stop")
+                cancel_reset_btn = gr.Button("Cancel")
 
     # Sign-in: one shared output list for every outcome (new / returning / error).
     gate_outputs = [
-        email_state, chatbot, display_state, convo_state, followups,
-        can_save, revision,
-        email_panel, intake_panel, chat_panel, status_md, switch_btn, back_btn,
-        msg,
+        user_id_state, email_state, chatbot, display_state, convo_state,
+        followups, can_save, revision, uid_attempts,
+        user_badge, email_panel, intake_panel, chat_panel, status_md,
+        switch_btn, msg, reset_confirm, restart_btn,
     ] + radios
+    gate_inputs = [user_id_box, email_box, uid_attempts]
 
-    email_btn.click(enter_email, inputs=[email_box], outputs=gate_outputs)
-    email_box.submit(enter_email, inputs=[email_box], outputs=gate_outputs)
-    switch_btn.click(switch_email, inputs=None, outputs=gate_outputs + [email_box])
+    email_btn.click(sign_in, inputs=gate_inputs, outputs=gate_outputs)
+    user_id_box.submit(sign_in, inputs=gate_inputs, outputs=gate_outputs)
+    email_box.submit(sign_in, inputs=gate_inputs, outputs=gate_outputs)
+    switch_btn.click(switch_email, inputs=None,
+                     outputs=gate_outputs + [user_id_box, email_box])
 
     # Save the questionnaire as it is filled in, so a half-finished intake
     # survives a closed tab.
@@ -909,35 +1085,38 @@ with gr.Blocks(title="MyeAI (Myeloma AI)", css=CSS,
         inputs=[api_key, email_state, can_save, revision,
                 display_state, convo_state, followups] + radios,
         outputs=[chatbot, display_state, convo_state, followups, revision,
-                 intake_panel, chat_panel, back_btn],
+                 intake_panel, chat_panel],
     )
     send_btn.click(
         respond,
         inputs=[msg, display_state, convo_state, followups, api_key, email_state,
                 can_save, revision],
-        outputs=[chatbot, display_state, convo_state, followups, revision, msg],
+        outputs=[chatbot, display_state, convo_state, followups, revision, msg,
+                 reset_confirm, restart_btn],
     )
     msg.submit(
         respond,
         inputs=[msg, display_state, convo_state, followups, api_key, email_state,
                 can_save, revision],
-        outputs=[chatbot, display_state, convo_state, followups, revision, msg],
+        outputs=[chatbot, display_state, convo_state, followups, revision, msg,
+                 reset_confirm, restart_btn],
     )
-    review_btn.click(
-        review_answers,
-        inputs=[email_state, can_save] + radios,
-        outputs=[intake_panel, chat_panel, back_btn] + radios,
+    # Start Over warns first; only the confirmation actually erases anything.
+    restart_btn.click(
+        show_reset_warning,
+        inputs=None,
+        outputs=[reset_confirm, restart_btn],
     )
-    back_btn.click(
-        back_to_chat,
+    cancel_reset_btn.click(
+        cancel_reset,
         inputs=None,
-        outputs=[intake_panel, chat_panel, back_btn],
+        outputs=[reset_confirm, restart_btn],
     )
-    restart_btn.click(
+    confirm_reset_btn.click(
         reset_all,
         inputs=[email_state, can_save, revision],
         outputs=[chatbot, display_state, convo_state, followups, revision,
-                 intake_panel, chat_panel, back_btn, msg] + radios,
+                 intake_panel, chat_panel, msg, reset_confirm, restart_btn] + radios,
     )
 
 if __name__ == "__main__":

supabase_schema.sql

@@ -13,6 +13,10 @@
 -- ----------------------------------------------------------------------------
 create table if not exists public.p3_sessions (
     email        text primary key,
+    -- The participant's study User ID, entered alongside the email at sign-in.
+    -- Checked on every return visit: a mismatch is refused rather than letting
+    -- one participant open another's session by guessing an email address.
+    user_id      text,
     -- The 16 intake answers, in question order: ["Yes","No",...]
     answers      jsonb       not null default '[]'::jsonb,
     -- Full model-facing conversation, including the hidden profile seed turn.
@@ -38,6 +42,11 @@ alter table public.p3_sessions
     add column if not exists revision integer not null default 0;
 alter table public.p3_sessions
     add column if not exists answers_count integer not null default 0;
+alter table public.p3_sessions
+    add column if not exists user_id text;
+
+create index if not exists p3_sessions_user_id_idx
+    on public.p3_sessions (user_id);
 
 -- ----------------------------------------------------------------------------
 -- 2. Append-only log of every chat turn.
@@ -85,6 +94,7 @@ drop view if exists public.p3_session_overview;
 create view public.p3_session_overview
 with (security_invoker = on) as
 select
+    s.user_id,
     s.email,
     jsonb_array_length(s.answers)      as answers_saved,
     jsonb_array_length(s.chat_display) as visible_messages,

supabase_store.py

@@ -78,6 +78,29 @@ def is_valid_email(value):
     return _EMAIL_RE.match(email) is not None
 
 
+# ----------------------------------------------------------------------
+# User ID helpers
+# ----------------------------------------------------------------------
+# Study IDs vary a lot between sites, so this is permissive: it only insists on
+# a leading letter or digit and a sane length, and rejects control characters.
+_USER_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9 ._@#/+-]{0,63}$")
+
+
+def normalize_user_id(value):
+    """Trimmed form, with runs of internal whitespace collapsed to one space."""
+    return re.sub(r"\s+", " ", (value or "").strip())
+
+
+def is_valid_user_id(value):
+    return _USER_ID_RE.match(normalize_user_id(value)) is not None
+
+
+def user_ids_match(a, b):
+    """Compare two User IDs. Case- and spacing-insensitive, so a participant is
+    not locked out by typing 'p3-014' instead of 'P3-014'."""
+    return normalize_user_id(a).casefold() == normalize_user_id(b).casefold()
+
+
 def _now_iso():
     return datetime.now(timezone.utc).isoformat()
 
@@ -238,7 +261,7 @@ class SupabaseStore:
             return data[0], None
         return None, None
 
-    def ensure_session(self, email):
+    def ensure_session(self, email, user_id=None):
         """Create the row if this email is new. Returns (row_or_None, error)."""
         email = normalize_email(email)
         if not email:
@@ -249,12 +272,19 @@ class SupabaseStore:
         if row is not None:
             return row, None
         now = _now_iso()
+        body = {"email": email, "created_at": now, "updated_at": now}
+        if user_id is not None:
+            body["user_id"] = user_id
+        prefer = "return=representation,resolution=merge-duplicates"
         ok, data, err = self._request(
-            "POST", self.sessions_table,
-            body={"email": email, "created_at": now, "updated_at": now},
             # merge-duplicates makes a concurrent double-submit harmless.
-            prefer="return=representation,resolution=merge-duplicates",
-        )
+            "POST", self.sessions_table, body=body, prefer=prefer)
+        if not ok and "user_id" in body and _missing_column(err, "user_id"):
+            # A project that has not re-run supabase_schema.sql yet. Create the
+            # session without the User ID rather than refusing to save at all.
+            body.pop("user_id", None)
+            ok, data, err = self._request(
+                "POST", self.sessions_table, body=body, prefer=prefer)
         if not ok:
             return None, err
         if isinstance(data, list) and data:
@@ -262,7 +292,7 @@ class SupabaseStore:
         return None, None
 
     def save_session(self, email, answers=None, convo=None, chat_display=None,
-                     followups=None, expected_revision=None):
+                     followups=None, user_id=None, expected_revision=None):
         """Update the supplied fields for this email, inserting if absent.
 
         Only fields that are not None are written, so a mid-chat save does not
@@ -291,6 +321,8 @@ class SupabaseStore:
             payload["chat_display"] = chat_display
         if followups is not None:
             payload["followups"] = int(followups)
+        if user_id is not None:
+            payload["user_id"] = user_id
 
         params = {"email": "eq." + email}
         guarded = expected_revision is not None
@@ -305,16 +337,21 @@ class SupabaseStore:
         if not ok:
             # A project created before the hardening columns existed: drop them
             # and retry rather than refusing to save at all.
-            if _missing_column(err, "answers_count"):
-                payload.pop("answers_count", None)
-                ok, data, err = self._request(
-                    "PATCH", self.sessions_table, params=params, body=payload,
-                    prefer="return=representation")
+            for optional in ("answers_count", "user_id"):
+                if not ok and _missing_column(err, optional):
+                    payload.pop(optional, None)
+                    ok, data, err = self._request(
+                        "PATCH", self.sessions_table, params=params, body=payload,
+                        prefer="return=representation")
             if not ok and guarded and _missing_column(err, "revision"):
-                return self.save_session(
+                retry_ok, _unused, retry_err = self.save_session(
                     email, answers=answers, convo=convo,
                     chat_display=chat_display, followups=followups,
-                    expected_revision=None)
+                    user_id=user_id, expected_revision=None)
+                # The column does not exist, so there is no revision to report.
+                # Hand back the caller's own value rather than None, which would
+                # otherwise end up in the page's revision state.
+                return retry_ok, expected_revision, retry_err
             if not ok:
                 return False, expected_revision, err
         if isinstance(data, list) and data:
@@ -413,7 +450,7 @@ class SupabaseStore:
             return False
         if stored_revision != int(expected_revision) + 1:
             return False
-        for key in ("answers", "convo", "chat_display", "followups"):
+        for key in ("answers", "convo", "chat_display", "followups", "user_id"):
             if key in payload and existing.get(key) != payload[key]:
                 return False
         return True

verify_supabase.py

@@ -18,7 +18,7 @@ import sys
 import time
 
 from supabase_store import (SupabaseStore, is_valid_email, normalize_email,
-                            CONFLICT)
+                            is_valid_user_id, user_ids_match, CONFLICT)
 
 PASS, FAIL = "  PASS  ", "  FAIL  "
 failures = []
@@ -62,8 +62,11 @@ def main():
     row, err = store.load_session(email)
     check("unseen email reads back as new", row is None and err is None, str(err))
 
-    row, err = store.ensure_session(email)
+    row, err = store.ensure_session(email, user_id="P3-VERIFY")
     check("row can be created", row is not None, str(err))
+    check("User ID validator accepts the study ID", is_valid_user_id("P3-VERIFY"))
+    check("User ID stored with the session",
+          (row or {}).get("user_id") == "P3-VERIFY", str((row or {}).get("user_id")))
 
     partial = ["Yes", "No", "Yes"] + [None] * 13
     ok, err = store.save_answers_monotonic(email, partial)
@@ -115,6 +118,13 @@ def main():
         check("revision column present (run the latest supabase_schema.sql)",
               "revision" in row, str(sorted(row))[:120])
         check("answers_count column present", "answers_count" in row, str(sorted(row))[:120])
+        check("user_id column present", "user_id" in row, str(sorted(row))[:120])
+        check("User ID survives the round trip", row.get("user_id") == "P3-VERIFY",
+              str(row.get("user_id")))
+        check("a returning participant's User ID would match",
+              user_ids_match(row.get("user_id"), "p3-verify"))
+        check("a wrong User ID would not match",
+              not user_ids_match(row.get("user_id"), "P3-SOMEONE-ELSE"))
     msgs, err = store.load_messages(email)
     check("message log readable", err is None and len(msgs) == 2, f"{len(msgs)} rows, {err}")