From ffb16258a608ce07d4e1b3b4accddcc68b81688d Mon Sep 17 00:00:00 2001
From: Arda Erzin <ardaerzin@gmail.com>
Date: Thu, 30 Jul 2026 14:54:06 +0300
Subject: [PATCH 01/19] feat(mobile): steer-lite deny-with-redirect behind the
 steer flag

The approval dock gains a flag-gated Redirect control that sends the denial and a
short instruction in one respond call. Delivery is cold-replay-only: a warm-parked
resume answers the harness gate on the still-pending original prompt and never
prompts again, so the note is dropped (measured live; the model then re-tried the
denied work with a sibling tool and raised a new gate). The harness has no
reject-with-feedback channel either - PermissionReply is once|always|reject - so
the control stays hidden unless NEXT_PUBLIC_AGENT_CHAT_STEER=true, matching the
desktop flag.
---
 .../sessions/interactions_dispatcher.py       |   8 ++
 .../2026-07-27-mobile-approvals-steering.md   |  92 ++++++++++++++
 web/mobile/src/features/chat/ApprovalDock.tsx | 118 ++++++++++++++----
 web/mobile/src/features/chat/steer.ts         |  33 +++++
 .../src/features/chat/useApprovalActions.ts   |  25 +++-
 .../src/features/chat/useSessionWatch.ts      |   4 +-
 web/mobile/tests/unit/steer.test.ts           |  42 +++++++
 7 files changed, 288 insertions(+), 34 deletions(-)
 create mode 100644 web/mobile/src/features/chat/steer.ts
 create mode 100644 web/mobile/tests/unit/steer.test.ts

diff --git a/api/oss/src/tasks/asyncio/sessions/interactions_dispatcher.py b/api/oss/src/tasks/asyncio/sessions/interactions_dispatcher.py
index c9a31e04a5..693945b28e 100644
--- a/api/oss/src/tasks/asyncio/sessions/interactions_dispatcher.py
+++ b/api/oss/src/tasks/asyncio/sessions/interactions_dispatcher.py
@@ -185,6 +185,14 @@ def compose_approval_messages(
     warm-parked sandbox still fingerprint-matches and resumes live). An optional
     deny-with-redirect ``message`` is appended as a trailing user message, which the
     fingerprint's prior-conversation slice excludes.
+
+    Where that note is DELIVERED is asymmetric, and verified live (2026-07-30). A warm resume
+    answers the parked harness gate on the still-pending original prompt and sends no new
+    prompt (``run-turn.ts``: the resume branch reuses the parked ``promptPromise``), so the
+    note never reaches the model — only a cold replay closes the replayed transcript with it.
+    Fingerprint parity therefore makes the note undeliverable in the common case; mobile's
+    steer control stays flag-gated off until the runner can carry a redirect in-band with the
+    denial (#5444). The note is still persisted as a user record either way.
     """
     messages = build_wire_messages(records)
     gated_id = resolve_gated_tool_call_id(records, interaction, answer)
diff --git a/docs/design/agenta-mobile/plans/2026-07-27-mobile-approvals-steering.md b/docs/design/agenta-mobile/plans/2026-07-27-mobile-approvals-steering.md
index ead77482d7..f1586ba98c 100644
--- a/docs/design/agenta-mobile/plans/2026-07-27-mobile-approvals-steering.md
+++ b/docs/design/agenta-mobile/plans/2026-07-27-mobile-approvals-steering.md
@@ -264,6 +264,7 @@ run).
   next send) — mirror the worktree's envelope exactly so the two implementations converge.
   **Dependency flag:** UX blocked on the same harness limitation; do not enable by default
   until #5444 (runner reject-with-feedback) exists.
+  **BUILT 2026-07-30, flag OFF — see §7 for the live delivery measurement.**
 
 ### Phase M2 — BE: wire the out-of-band respond path (small, separable)
 
@@ -326,6 +327,8 @@ path for the "approve from the notification" dream, else it just opens the chat
 3. **Steer-lite: WAIT** — do not ship deny-with-redirect now; wait for the runner's
    reject-with-feedback (#5444). ⚠️ **FOLLOW-UP (do not forget): Arda may ask for this
    implementation next**; the M1.5 task stays specced and unbuilt.
+   → **Revisited 2026-07-30 (Arda: "go ahead").** Built, flag OFF; the wait still stands and
+   is now measured rather than inferred — §7.
 4. **Warm-park TTL: BUMP** when a pending interaction exists (phone-latency answers should
    warm-resume, not cold-replay).
 5. **M2: build it in this workstream** ("finish this yourself") — do not hand to JP.
@@ -412,3 +415,92 @@ session — an un-gated-concurrent-`/invoke` hazard, not a lock-contract one.
 **Also worth knowing:** `updated_at` is bumped by non-heartbeat writers (attach/detach,
 rename), so watcher churn can hold an orphan's sweep clock open — now a 30-minute window for
 alive-but-idle rows rather than 5.
+
+---
+
+## 7. Steer-lite (M1.5): built, flag OFF — the redirect is cold-replay-only (2026-07-30)
+
+### 7.1 What a denial can carry today
+
+Nothing but the verdict. The harness reply type is a closed union —
+`PermissionReply = "once" | "always" | "reject"` (`services/runner/node_modules/sandbox-agent`,
+`Session.respondPermission(permissionId, reply)`) — and both runner call sites pass exactly that:
+`replyPermission` (`acp-interactions.ts:242-280`, warm/deny path) and the cold decision map
+(`responder.ts` `storedApprovalDecisionOf` → `{approved: boolean, interactionToken?}`). The durable
+plane matches: the answer that resolves an interaction row is `{approved, toolCallId}`. There is no
+feedback/message field anywhere between the client and the model. The denial text the model reads
+(`"Denied by the permission policy."`) is a **static** string the in-sandbox Pi extension returns
+(`extensions/agenta.ts:119,206,334`); on Claude ACP it is the harness's own "user refused
+permission". So "deny with a reason" does not exist at any layer — that is #5444.
+
+### 7.2 Where the redirect note IS delivered
+
+`{approved:false, message}` on `POST /sessions/interactions/{id}/respond` already rides: the
+dispatcher appends the note as a trailing user message (`compose_approval_messages`). Delivery is
+asymmetric, and it lands on the wrong side of the split for mobile:
+
+- **Cold replay — DELIVERED.** No parked sandbox (or a fingerprint mismatch) ⇒ `buildTurnText`
+  replays the transcript, renders the denial as `[user DENIED <tool>; the call was not executed.]`,
+  and closes with `Continue the conversation. The user now says:\n<note>` — the note IS the prompt.
+- **Warm resume — DROPPED.** A parked sandbox that fingerprint-matches resumes by calling
+  `respondPermission` on the still-pending ORIGINAL prompt and takes the
+  `if (opts.resume)` branch in `run-turn.ts:744-800`, which **never calls `session.prompt`**. The
+  trailing note is not sent to the model at all. Worse, it is still persisted as a `user` record
+  (the runner records `resolvePromptText(request)` as the turn's user message), so the transcript
+  shows the instruction as if it had been delivered.
+
+Warm is the DEFAULT for a phone answer since this workstream bumped `approvalTtlMs` to 30 minutes
+(§4b-4) and since the dispatcher was deliberately given fingerprint parity so mobile answers
+warm-resume. In other words the two earlier decisions that made mobile approvals fast are exactly
+what make a mobile steer undeliverable.
+
+**Live measurement** (ephemeral projects, `scratchpad/steer_arm.py {warm,cold}`; identical answer
+payload, redirect = "Do not create any file … reply with exactly the single word PIVOTED"):
+
+| arm | runner dispatch | outcome |
+| --- | --- | --- |
+| `warm` (respond dispatcher, the mobile path) | `[keepalive] resume … answered=1 approve=0 reject=1 tool=Bash` | note NOT delivered; model reasoned *"It appears I don't have permission … Let me try using the write tool instead"* and raised a NEW gate on `Write` |
+| `cold` (same envelope, no fingerprint parity) | `approval-mismatch (history); evict + cold` → `[HITL] cold replay: … resumeFrame=none, turnText 480 chars` | note delivered; agent replied exactly `PIVOTED`, wrote no file, raised no new gate |
+
+The warm arm is the negative result this section exists for: a bare deny makes the model flail into
+a sibling gate, which is precisely the UX #5444 is meant to fix.
+
+### 7.3 What shipped
+
+- `web/mobile/src/features/chat/steer.ts` — `isSteerEnabled()` (`NEXT_PUBLIC_AGENT_CHAT_STEER ===
+  "true"`, desktop-parity spelling of `isAgentChatSteerEnabled`) and `buildApprovalAnswer`, which
+  trims the note and omits it entirely when blank (a blank redirect is a plain deny, never an empty
+  trailing user message).
+- `ApprovalDock.tsx` — a flag-gated "Redirect" control; opening it swaps the decision row for a
+  raw textarea + Cancel / "Deny & send", mirroring the desktop dock's panel swap. The note is reset
+  whenever the acted-on gate changes. No new shadcn component, no motion (raw-UI ethos).
+- `useApprovalActions.ts` — `respond({approvalId, approved, message?})` through the same
+  `respondInteraction` path: fire-and-forget, single-flight `busyRef`, `phase` transitions, 60s
+  re-arm, settle on `pendingCount === 0`, 409 treated as benign.
+- No dispatcher change was needed (`message` already rides and is pinned by
+  `test_denial_with_message_appends_a_trailing_user_note`); its docstring now records the delivery
+  asymmetry.
+
+**Gated:** the control is hidden unless the flag is `true`, so no user can hit the silent drop. The
+implementation ships intact behind it — flipping the flag is the entire enablement once the runner
+carries a redirect in-band with the denial.
+
+### 7.4 Why not "just make it work"
+
+Three alternatives were traced and rejected:
+
+- **Deliver it on the warm path (runner).** Requires either a second `session.prompt` inside the
+  resume turn (new turn semantics: usage, run limits, otel spans, loop risk) or a real
+  reject-with-feedback channel — which is not a runner-local change: `PermissionReply` is a
+  closed ACP union and the denial text is produced in-sandbox by the Pi extension. Also unverifiable
+  here: the runner does not hot-reload TS.
+- **Force the cold path from the API when a note is present.** It works (the `cold` arm proves the
+  end-to-end behavior), but the only lever available is deliberately breaking the history
+  fingerprint. That logs an intentional behavior as `approval-mismatch (history)`, throws away a
+  warm sandbox, and silently reverts to dropping the note the moment the runner relaxes that
+  comparison (the idle branch already skips it for minimal-history clients). Needs a real wire flag
+  to be honest, i.e. a runner change.
+- **Deny now, deliver the note as a follow-up turn** (desktop's shape). Broken on mobile: after a
+  denial the model typically re-attempts with a sibling tool and the session parks on a NEW gate
+  (observed in the warm arm), so "wait for idle, then send" can block indefinitely — and mobile has
+  no send path to queue onto in the first place.
diff --git a/web/mobile/src/features/chat/ApprovalDock.tsx b/web/mobile/src/features/chat/ApprovalDock.tsx
index afc5c63e17..bd9c91389d 100644
--- a/web/mobile/src/features/chat/ApprovalDock.tsx
+++ b/web/mobile/src/features/chat/ApprovalDock.tsx
@@ -1,6 +1,9 @@
+import {useEffect, useState} from "react"
+
 import type {PendingApproval} from "@agenta/chat/model"
 
 import {summarizeApprovalInput} from "./approvalInputSummary"
+import {isSteerEnabled} from "./steer"
 import type {ApprovalActions} from "./useApprovalActions"
 
 /**
@@ -19,10 +22,20 @@ export const ApprovalDock = ({
     actions: ApprovalActions
 }) => {
     const current = approvals[0]
+    // Steer-lite: an optional redirect note sent WITH the denial. Flag-gated — see [[isSteerEnabled]].
+    const [steerOpen, setSteerOpen] = useState(false)
+    const [steerMessage, setSteerMessage] = useState("")
+    const currentId = current?.approvalId
+    useEffect(() => {
+        setSteerOpen(false)
+        setSteerMessage("")
+    }, [currentId])
+
     if (!current) return null
     const count = approvals.length
     const busy = actions.phase === "resuming"
     const summary = summarizeApprovalInput(current.input)
+    const canSteer = isSteerEnabled()
     return (
         <div className="border-border bg-background shrink-0 border-t px-4 pt-3 pb-[calc(0.75rem+env(safe-area-inset-bottom))]">
             <div className="flex items-center gap-2">
@@ -44,38 +57,91 @@ export const ApprovalDock = ({
                     </pre>
                 </div>
             ) : null}
-            <div className="mt-3 flex items-center gap-2">
-                {count > 1 ? (
+            {/* While steering, the redirect panel replaces the decision row: an explicit
+                deny+redirect shouldn't leave Approve competing with it. */}
+            {steerOpen ? (
+                <div className="mt-3 flex flex-col gap-2">
+                    <p className="text-muted-foreground text-[11px]">
+                        Deny this step and tell the agent what to do instead.
+                    </p>
+                    <textarea
+                        autoFocus
+                        rows={3}
+                        value={steerMessage}
+                        onChange={(event) => setSteerMessage(event.target.value)}
+                        disabled={busy}
+                        placeholder="e.g. write to staging, not prod"
+                        className="border-border bg-muted resize-none rounded border p-2 text-xs disabled:opacity-50"
+                    />
+                    <div className="flex items-center gap-2">
+                        <button
+                            type="button"
+                            disabled={busy}
+                            className="text-muted-foreground min-h-11 px-1 text-xs disabled:opacity-50"
+                            onClick={() => setSteerOpen(false)}
+                        >
+                            Cancel
+                        </button>
+                        <button
+                            type="button"
+                            disabled={busy || !steerMessage.trim()}
+                            className="border-border ml-auto min-h-11 rounded border px-3 text-xs disabled:opacity-50"
+                            onClick={() =>
+                                actions.respond({
+                                    approvalId: current.approvalId,
+                                    approved: false,
+                                    message: steerMessage,
+                                })
+                            }
+                        >
+                            Deny &amp; send
+                        </button>
+                    </div>
+                </div>
+            ) : (
+                <div className="mt-3 flex items-center gap-2">
+                    {count > 1 ? (
+                        <button
+                            type="button"
+                            disabled={busy}
+                            className="border-border min-h-11 rounded border px-3 text-xs disabled:opacity-50"
+                            onClick={() => actions.approveAll()}
+                        >
+                            Approve all
+                        </button>
+                    ) : null}
                     <button
                         type="button"
                         disabled={busy}
                         className="border-border min-h-11 rounded border px-3 text-xs disabled:opacity-50"
-                        onClick={() => actions.approveAll()}
+                        onClick={() =>
+                            actions.respond({approvalId: current.approvalId, approved: false})
+                        }
                     >
-                        Approve all
+                        Deny
                     </button>
-                ) : null}
-                <button
-                    type="button"
-                    disabled={busy}
-                    className="border-border min-h-11 rounded border px-3 text-xs disabled:opacity-50"
-                    onClick={() =>
-                        actions.respond({approvalId: current.approvalId, approved: false})
-                    }
-                >
-                    Deny
-                </button>
-                <button
-                    type="button"
-                    disabled={busy}
-                    className="bg-primary text-primary-foreground ml-auto min-h-11 rounded px-4 text-xs font-medium disabled:opacity-50"
-                    onClick={() =>
-                        actions.respond({approvalId: current.approvalId, approved: true})
-                    }
-                >
-                    Approve
-                </button>
-            </div>
+                    {canSteer ? (
+                        <button
+                            type="button"
+                            disabled={busy}
+                            className="text-muted-foreground min-h-11 px-1 text-xs disabled:opacity-50"
+                            onClick={() => setSteerOpen(true)}
+                        >
+                            Redirect
+                        </button>
+                    ) : null}
+                    <button
+                        type="button"
+                        disabled={busy}
+                        className="bg-primary text-primary-foreground ml-auto min-h-11 rounded px-4 text-xs font-medium disabled:opacity-50"
+                        onClick={() =>
+                            actions.respond({approvalId: current.approvalId, approved: true})
+                        }
+                    >
+                        Approve
+                    </button>
+                </div>
+            )}
             {busy ? <p className="text-muted-foreground mt-2 text-xs">Resuming…</p> : null}
             {actions.phase === "error" && actions.errorText ? (
                 <p className="text-destructive mt-2 text-xs">{actions.errorText}</p>
diff --git a/web/mobile/src/features/chat/steer.ts b/web/mobile/src/features/chat/steer.ts
new file mode 100644
index 0000000000..7692311898
--- /dev/null
+++ b/web/mobile/src/features/chat/steer.ts
@@ -0,0 +1,33 @@
+import {getEnv} from "@/lib/env"
+
+/**
+ * Steer-lite (deny + redirect): gates the approval dock's "Redirect" control, mirroring the
+ * desktop flag `NEXT_PUBLIC_AGENT_CHAT_STEER` (`isAgentChatSteerEnabled`). OFF by default.
+ *
+ * Why it stays off: the redirect note only reaches the model on the runner's COLD-replay path,
+ * where it closes the replayed transcript as the next user turn. A warm-parked sandbox — the
+ * normal case for a phone answer since the approval park TTL became 30 minutes — resumes by
+ * answering the harness gate on the still-pending original prompt and sends no new prompt at
+ * all, so the note is dropped (verified live: the model re-tried the denied work with another
+ * tool). The harness has no reject-with-feedback channel to carry it either
+ * (`PermissionReply = "once" | "always" | "reject"`). Flip this on once the runner delivers a
+ * redirect in-band with the denial (#5444).
+ */
+export const isSteerEnabled = (): boolean =>
+    (getEnv("NEXT_PUBLIC_AGENT_CHAT_STEER") || "").toLowerCase() === "true"
+
+/** Extends `Record` because the respond endpoint's `answer` is an open payload. */
+export interface ApprovalAnswer extends Record<string, unknown> {
+    approved: boolean
+    message?: string
+}
+
+/**
+ * The `answer` payload for `POST /sessions/interactions/{id}/respond`. A blank or whitespace-only
+ * note is omitted entirely, so a redirect with no text is a plain deny rather than an empty
+ * trailing user message in the resumed conversation.
+ */
+export const buildApprovalAnswer = (approved: boolean, message?: string): ApprovalAnswer => {
+    const note = message?.trim()
+    return note ? {approved, message: note} : {approved}
+}
diff --git a/web/mobile/src/features/chat/useApprovalActions.ts b/web/mobile/src/features/chat/useApprovalActions.ts
index 64a19c162d..35ce41154e 100644
--- a/web/mobile/src/features/chat/useApprovalActions.ts
+++ b/web/mobile/src/features/chat/useApprovalActions.ts
@@ -7,6 +7,7 @@ import {
 } from "@agenta/entities/session"
 
 import {selectApprovalTargets, type ApprovalTarget} from "./approvalTargets"
+import {buildApprovalAnswer} from "./steer"
 
 export type ResumePhase = "idle" | "resuming" | "error"
 
@@ -19,8 +20,12 @@ const respondErrorText = (error: unknown): string => {
 export interface ApprovalActions {
     phase: ResumePhase
     errorText: string | null
-    /** Answer one gate. Deny also resumes (the runner needs the denial round-trip). */
-    respond: (args: {approvalId: string; approved: boolean}) => void
+    /**
+     * Answer one gate. Deny also resumes (the runner needs the denial round-trip). `message` is
+     * the steer-lite redirect note that rides with a denial — see [[isSteerEnabled]] for where it
+     * is actually delivered.
+     */
+    respond: (args: {approvalId: string; approved: boolean; message?: string}) => void
     /** Approve every pending gate — one respond call per gate (the endpoint is per-interaction). */
     approveAll: () => void
 }
@@ -66,7 +71,7 @@ export const useApprovalActions = ({
     }, [phase])
 
     const submit = useCallback(
-        async (target: ApprovalTarget, approved: boolean) => {
+        async (target: ApprovalTarget, approved: boolean, message?: string) => {
             if (busyRef.current) return
             busyRef.current = true
             setPhase("resuming")
@@ -92,7 +97,7 @@ export const useApprovalActions = ({
                         await respondInteraction({
                             interactionId: row.id as string,
                             projectId,
-                            answer: {approved},
+                            answer: buildApprovalAnswer(approved, message),
                         })
                         answered += 1
                     } catch (err) {
@@ -114,8 +119,16 @@ export const useApprovalActions = ({
     )
 
     const respond = useCallback(
-        ({approvalId, approved}: {approvalId: string; approved: boolean}) => {
-            void submit({approvalId}, approved)
+        ({
+            approvalId,
+            approved,
+            message,
+        }: {
+            approvalId: string
+            approved: boolean
+            message?: string
+        }) => {
+            void submit({approvalId}, approved, message)
         },
         [submit],
     )
diff --git a/web/mobile/src/features/chat/useSessionWatch.ts b/web/mobile/src/features/chat/useSessionWatch.ts
index 5f30f333da..2141d7e233 100644
--- a/web/mobile/src/features/chat/useSessionWatch.ts
+++ b/web/mobile/src/features/chat/useSessionWatch.ts
@@ -2,13 +2,13 @@ import {useEffect, useRef, useState} from "react"
 
 import {useQueryClient} from "@tanstack/react-query"
 
+import {tryRefreshSession} from "@/lib/auth"
+
 import {actionableInteractionsQueryKey} from "../sessions/useActionableInteractions"
 import {livenessQueryKey} from "../sessions/useLivenessPoll"
 
 import {sessionWatchUrl, watchRetryDelayMs} from "./watchRelay"
 
-import {tryRefreshSession} from "@/lib/auth"
-
 /** Minimum spacing between two reconnect revalidations, so a reconnect loop can't fan out
  * into one full records refetch per attempt. */
 const MIN_INTERVAL_MS = 3_000
diff --git a/web/mobile/tests/unit/steer.test.ts b/web/mobile/tests/unit/steer.test.ts
new file mode 100644
index 0000000000..7520db7a52
--- /dev/null
+++ b/web/mobile/tests/unit/steer.test.ts
@@ -0,0 +1,42 @@
+import {afterEach, describe, expect, it} from "vitest"
+
+import {buildApprovalAnswer, isSteerEnabled} from "../../src/features/chat/steer"
+
+const FLAG = "NEXT_PUBLIC_AGENT_CHAT_STEER"
+
+afterEach(() => {
+    delete process.env[FLAG]
+})
+
+describe("buildApprovalAnswer", () => {
+    it("omits the note entirely for a plain approve/deny", () => {
+        expect(buildApprovalAnswer(true)).toEqual({approved: true})
+        expect(buildApprovalAnswer(false)).toEqual({approved: false})
+    })
+
+    it("trims the redirect note onto a denial", () => {
+        expect(buildApprovalAnswer(false, "  write to staging  ")).toEqual({
+            approved: false,
+            message: "write to staging",
+        })
+    })
+
+    it("treats a blank note as no note — never an empty trailing user message", () => {
+        expect(buildApprovalAnswer(false, "   \n ")).toEqual({approved: false})
+    })
+})
+
+describe("isSteerEnabled", () => {
+    it("is off unless the flag is explicitly true (desktop parity)", () => {
+        expect(isSteerEnabled()).toBe(false)
+        process.env[FLAG] = "false"
+        expect(isSteerEnabled()).toBe(false)
+        process.env[FLAG] = "1"
+        expect(isSteerEnabled()).toBe(false)
+    })
+
+    it("is on for true in any case", () => {
+        process.env[FLAG] = "TRUE"
+        expect(isSteerEnabled()).toBe(true)
+    })
+})

From 0412de91c0e29cdc481b68fd1f76b135f0e6e1b1 Mon Sep 17 00:00:00 2001
From: Arda Erzin <ardaerzin@gmail.com>
Date: Fri, 31 Jul 2026 08:22:03 +0300
Subject: [PATCH 02/19] feat(web): hand a mobile-initiated OAuth callback back
 to /m
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Providers only ever redirect to the one URI registered for them, the desktop
`/auth/callback/<providerId>`, so a mobile SSO flow could never land in /m and
the mobile sign-in had to tell users to switch to the desktop app.

The mobile app now marks the flow with a short-lived cookie before leaving for
the provider. The desktop forward gate reads it and forwards the landing to
`/m/auth/callback/...` with the query intact, where the OAuth state (same-origin
sessionStorage) is still readable — no new redirect URI has to be registered
with any provider. `?view=desktop` still wins, and the other desktop-only
exceptions are untouched.

The reverse gate also stops bouncing any `/auth/callback` off /m: an OAuth
landing must complete where it lands or the one-time code is lost.
---
 web/mobile/src/middleware.ts                  |   4 +
 web/mobile/tests/unit/middleware.test.ts      |  10 ++
 .../src/utils/mobileGate/index.ts             |  48 ++++++--
 .../tests/unit/mobileGate.test.ts             | 103 ++++++++++++++----
 4 files changed, 135 insertions(+), 30 deletions(-)

diff --git a/web/mobile/src/middleware.ts b/web/mobile/src/middleware.ts
index f7bcfde31b..d8efcc68b7 100644
--- a/web/mobile/src/middleware.ts
+++ b/web/mobile/src/middleware.ts
@@ -22,6 +22,7 @@ const VIEW_PARAM = "view"
 const GATE_COOKIE_MAX_AGE = 60 * 60 * 24 * 180
 
 const MOBILE_UA_RE = /Android|iPhone|iPod|iPad|webOS|BlackBerry|IEMobile|Opera Mini|Mobile/i
+const AUTH_CALLBACK_RE = /^\/auth\/callback(\/|$)/
 
 function isMobileDevice(header: (name: string) => string | null): boolean {
     const hint = header("sec-ch-ua-mobile")
@@ -84,6 +85,9 @@ export function middleware(request: NextRequest) {
             return response
         }
 
+        // An OAuth landing completes wherever it lands — bouncing it drops the
+        // one-time code and strands the flow.
+        if (AUTH_CALLBACK_RE.test(pathname)) return NextResponse.next()
         if (request.cookies.get(MOBILE_OPTIN_COOKIE)?.value) return NextResponse.next()
         if (isMobileDevice(header)) return NextResponse.next()
 
diff --git a/web/mobile/tests/unit/middleware.test.ts b/web/mobile/tests/unit/middleware.test.ts
index a00f4cde88..4d62367c93 100644
--- a/web/mobile/tests/unit/middleware.test.ts
+++ b/web/mobile/tests/unit/middleware.test.ts
@@ -76,6 +76,16 @@ describe("mobile reverse gate middleware", () => {
         expect(setCookie).toContain("Path=/")
     })
 
+    it("never bounces an OAuth callback landing off /m", () => {
+        const res = middleware(req("/m/auth/callback/google?code=abc", doc(DESKTOP_UA)))
+        expect(res.headers.get("location")).toBeNull()
+    })
+
+    it("still bounces the mobile sign-in page for desktop UAs", () => {
+        const res = middleware(req("/m/auth", doc(DESKTOP_UA)))
+        expect(res.headers.get("location")).toBe("http://localhost:3000/auth")
+    })
+
     it("mobile UA passes untouched (no cookie, no redirect)", () => {
         const res = middleware(req("/m/", doc(MOBILE_UA)))
         expect(res.headers.get("location")).toBeNull()
diff --git a/web/packages/agenta-shared/src/utils/mobileGate/index.ts b/web/packages/agenta-shared/src/utils/mobileGate/index.ts
index 1a5e7507a5..1fbfa88576 100644
--- a/web/packages/agenta-shared/src/utils/mobileGate/index.ts
+++ b/web/packages/agenta-shared/src/utils/mobileGate/index.ts
@@ -15,6 +15,17 @@
 
 export const MOBILE_OPTOUT_COOKIE = "agenta-mobile-optout"
 export const MOBILE_OPTIN_COOKIE = "agenta-mobile-optin"
+/**
+ * Set by the mobile app right before it sends the browser to an OIDC provider,
+ * and cleared by /m/auth/callback. Providers only ever redirect to the ONE
+ * registered URI (the desktop `/auth/callback/<providerId>`), so this cookie is
+ * how the desktop gate knows a landing callback belongs to the mobile app and
+ * must be handed to /m — where the OAuth state lives in the same-origin
+ * sessionStorage. Short-lived (see MOBILE_AUTH_CALLBACK_MAX_AGE).
+ */
+export const MOBILE_AUTH_CALLBACK_COOKIE = "agenta-mobile-auth-callback"
+/** 10 minutes — matches SuperTokens' own OAuth state expiry. */
+export const MOBILE_AUTH_CALLBACK_MAX_AGE = 60 * 10
 /** Reserved query param: `view=desktop` | `view=mobile` set the escape cookies. */
 export const VIEW_PARAM = "view"
 /** 180 days, in seconds. */
@@ -58,11 +69,15 @@ export function isDocumentNavigation(input: Pick<GateInput, "method" | "header">
 
 /**
  * Desktop routes that must never redirect to /m (design.md documented
- * exceptions). /auth now maps to the mobile sign-in (→ /m/auth, auth-lite),
- * EXCEPT /auth/callback: the OAuth/SSO redirect landing must complete on the
- * desktop app (mobile has no SSO). /post-signup and /workspaces/accept are
- * permanently desktop-only.
+ * exceptions). /auth now maps to the mobile sign-in (→ /m/auth), EXCEPT
+ * /auth/callback: an OAuth/SSO redirect landing must never be bounced mid-flow,
+ * because the redirect URI is fixed at the provider. When the mobile app started
+ * the flow (MOBILE_AUTH_CALLBACK_COOKIE) the landing is forwarded to the mirror
+ * page under /m instead — see decideDesktopGate. /post-signup and
+ * /workspaces/accept are permanently desktop-only.
  */
+const AUTH_CALLBACK_RE = /^\/auth\/callback(\/|$)/
+
 const AUTH_RE = /^\/auth(\/|$)/
 
 /**
@@ -78,17 +93,13 @@ export function isTokenBearingAuthLink(pathname: string, search: string): boolea
     return Boolean(new URLSearchParams(search).get("token"))
 }
 
-const DESKTOP_EXCEPTIONS = [
-    /^\/auth\/callback(\/|$)/,
-    /^\/post-signup(\/|$)/,
-    /^\/workspaces\/accept(\/|$)/,
-]
+const DESKTOP_EXCEPTIONS = [AUTH_CALLBACK_RE, /^\/post-signup(\/|$)/, /^\/workspaces\/accept(\/|$)/]
 
 const PROJECT_PATH_RE = /^\/w\/([^/]+)\/p\/([^/]+)(\/|$)/
 
 /** Desktop URL → mobile equivalent (design.md "Gate and routing"). */
 export function mapDesktopToMobile(pathname: string, search: string): string {
-    // Mobile sign-in (auth-lite): /auth/callback never reaches here (exception).
+    // Mobile sign-in: /auth/callback never reaches here (handled as an exception).
     if (/^\/auth(\/|$)/.test(pathname)) return "/m/auth"
     const m = pathname.match(PROJECT_PATH_RE)
     if (m) {
@@ -144,7 +155,19 @@ export function decideDesktopGate(input: GateInput): GateDecision {
             }
         }
 
-        if (DESKTOP_EXCEPTIONS.some((re) => re.test(input.pathname))) return {kind: "pass"}
+        if (DESKTOP_EXCEPTIONS.some((re) => re.test(input.pathname))) {
+            // A provider redirect the MOBILE app started: hand it to /m verbatim
+            // (path + query) so /m/auth/callback can run signInAndUp against the
+            // same-origin sessionStorage state. Device-independent on purpose —
+            // the cookie is the intent, a desktop UA can be opted into /m.
+            if (
+                AUTH_CALLBACK_RE.test(input.pathname) &&
+                input.cookie(MOBILE_AUTH_CALLBACK_COOKIE)
+            ) {
+                return {kind: "redirect", location: `/m${input.pathname}${input.search}`}
+            }
+            return {kind: "pass"}
+        }
         // A one-time token completes where it landed; see isTokenBearingAuthLink.
         if (isTokenBearingAuthLink(input.pathname, input.search)) return {kind: "pass"}
         if (input.cookie(MOBILE_OPTOUT_COOKIE)) return {kind: "pass"}
@@ -173,6 +196,9 @@ export function decideMobileGate(input: GateInput): GateDecision {
             }
         }
 
+        // An OAuth landing completes wherever it lands — bouncing it drops the
+        // one-time code and strands the flow.
+        if (AUTH_CALLBACK_RE.test(input.pathname)) return {kind: "pass"}
         if (input.cookie(MOBILE_OPTIN_COOKIE)) return {kind: "pass"}
         if (isMobileDevice(input.header)) return {kind: "pass"}
 
diff --git a/web/packages/agenta-shared/tests/unit/mobileGate.test.ts b/web/packages/agenta-shared/tests/unit/mobileGate.test.ts
index e4ce071231..7805552a86 100644
--- a/web/packages/agenta-shared/tests/unit/mobileGate.test.ts
+++ b/web/packages/agenta-shared/tests/unit/mobileGate.test.ts
@@ -2,6 +2,7 @@ import {describe, expect, it} from "vitest"
 
 import {
     GATE_COOKIE_MAX_AGE,
+    MOBILE_AUTH_CALLBACK_COOKIE,
     MOBILE_OPTIN_COOKIE,
     MOBILE_OPTOUT_COOKIE,
     decideDesktopGate,
@@ -39,25 +40,6 @@ const docHeaders = (ua: string, extra: Record<string, string> = {}) => ({
 })
 
 describe("isMobileDevice", () => {
-    it("leaves a token-bearing auth link on desktop", () => {
-        // SuperTokens password-reset and invite links carry a one-time ?token=. Redirecting
-        // drops it twice over: mapDesktopToMobile returns a bare /m/auth, and mobile has no
-        // screen that consumes a token.
-        for (const pathname of ["/auth", "/auth/reset-password"]) {
-            expect(
-                decideDesktopGate(
-                    input({pathname, search: "?token=abc123", headers: docHeaders(MOBILE_UA)}),
-                ),
-            ).toEqual({kind: "pass"})
-        }
-    })
-
-    it("still redirects a plain auth link with no token", () => {
-        expect(
-            decideDesktopGate(input({pathname: "/auth", headers: docHeaders(MOBILE_UA)})),
-        ).toEqual({kind: "redirect", location: "/m/auth"})
-    })
-
     it("trusts sec-ch-ua-mobile ?1 over a desktop UA", () => {
         expect(
             isMobileDevice(
@@ -166,6 +148,73 @@ describe("decideDesktopGate", () => {
             })
         }
     })
+    it("leaves a token-bearing auth link on desktop", () => {
+        // SuperTokens password-reset and invite links carry a one-time ?token=. Redirecting
+        // drops it twice over: mapDesktopToMobile returns a bare /m/auth, and mobile has no
+        // screen that consumes a token.
+        for (const pathname of ["/auth", "/auth/reset-password"]) {
+            expect(
+                decideDesktopGate(
+                    input({pathname, search: "?token=abc123", headers: docHeaders(MOBILE_UA)}),
+                ),
+            ).toEqual({kind: "pass"})
+        }
+    })
+
+    it("still redirects a plain auth link with no token", () => {
+        expect(
+            decideDesktopGate(input({pathname: "/auth", headers: docHeaders(MOBILE_UA)})),
+        ).toEqual({kind: "redirect", location: "/m/auth"})
+    })
+
+    it("forwards an OAuth callback the mobile app started to /m, query intact", () => {
+        const i = input({
+            pathname: "/auth/callback/google",
+            search: "?code=abc&state=xyz",
+            headers: docHeaders(MOBILE_UA),
+        })
+        i.cookie = (name) => (name === MOBILE_AUTH_CALLBACK_COOKIE ? "1" : undefined)
+        expect(decideDesktopGate(i)).toEqual({
+            kind: "redirect",
+            location: "/m/auth/callback/google?code=abc&state=xyz",
+        })
+    })
+    it("forwards the mobile callback for a desktop UA too (the cookie is the intent)", () => {
+        const i = input({pathname: "/auth/callback/github", headers: docHeaders(DESKTOP_UA)})
+        i.cookie = (name) => (name === MOBILE_AUTH_CALLBACK_COOKIE ? "1" : undefined)
+        expect(decideDesktopGate(i)).toEqual({
+            kind: "redirect",
+            location: "/m/auth/callback/github",
+        })
+    })
+    it("leaves the other desktop-only exceptions alone even with the callback cookie", () => {
+        for (const pathname of ["/post-signup", "/workspaces/accept"]) {
+            const i = input({pathname, headers: docHeaders(MOBILE_UA)})
+            i.cookie = (name) => (name === MOBILE_AUTH_CALLBACK_COOKIE ? "1" : undefined)
+            expect(decideDesktopGate(i)).toEqual({kind: "pass"})
+        }
+    })
+    it("still passes an OAuth callback with no mobile marker", () => {
+        expect(
+            decideDesktopGate(
+                input({pathname: "/auth/callback/google", headers: docHeaders(MOBILE_UA)}),
+            ),
+        ).toEqual({kind: "pass"})
+    })
+    it("lets ?view=desktop win over the callback marker", () => {
+        const i = input({
+            pathname: "/auth/callback/google",
+            search: "?view=desktop",
+            headers: docHeaders(MOBILE_UA),
+        })
+        i.cookie = (name) => (name === MOBILE_AUTH_CALLBACK_COOKIE ? "1" : undefined)
+        expect(decideDesktopGate(i)).toEqual({
+            kind: "set-cookie-redirect",
+            cookie: MOBILE_OPTOUT_COOKIE,
+            clearCookie: MOBILE_OPTIN_COOKIE,
+            location: "/auth/callback/google",
+        })
+    })
     it("redirects mobile devices on desktop /auth to the mobile sign-in", () => {
         expect(
             decideDesktopGate(input({pathname: "/auth", headers: docHeaders(MOBILE_UA)})),
@@ -225,6 +274,22 @@ describe("decideMobileGate", () => {
             kind: "pass",
         })
     })
+    it("never bounces an OAuth callback landing off /m", () => {
+        expect(
+            decideMobileGate(
+                input({
+                    pathname: "/auth/callback/google",
+                    search: "?code=abc",
+                    headers: docHeaders(DESKTOP_UA),
+                }),
+            ),
+        ).toEqual({kind: "pass"})
+    })
+    it("still bounces the mobile sign-in page for desktop UAs", () => {
+        expect(
+            decideMobileGate(input({pathname: "/auth", headers: docHeaders(DESKTOP_UA)})),
+        ).toEqual({kind: "redirect", location: "/auth"})
+    })
     it("sets the opt-in cookie and strips the reserved param on ?view=mobile", () => {
         expect(
             decideMobileGate(

From c074b488241457672cbc37055be47176bc00677f Mon Sep 17 00:00:00 2001
From: Arda Erzin <ardaerzin@gmail.com>
Date: Fri, 31 Jul 2026 08:22:16 +0300
Subject: [PATCH 03/19] =?UTF-8?q?feat(mobile):=20sign-in=20parity=20?=
 =?UTF-8?q?=E2=80=94=20email=20OTP,=20social=20providers,=20and=20org=20SS?=
 =?UTF-8?q?O?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

/m/auth only did email+password and told everyone else to use the desktop app.
It now offers every method the deployment enables, derived from the same env
flags as the desktop's getEffectiveAuthConfig:

- Passwordless: request a code, verify it, resend on a 60s cooldown, with each
  SuperTokens status mapped to a retry-in-place or a restart.
- Social: one button per configured OAuth client id, in the desktop's order,
  running the redirect flow through the shared device gate's mobile callback.
- Organization SSO: /auth/discover by work email, then the same redirect flow
  (404 on OSS reads as "no SSO", not an error).
- Email/password unchanged; an SSO-only deployment no longer shows an email
  form, and a deployment with nothing enabled says so instead of rendering an
  empty card.

Every route lands the same way it already did — invalidate the cached
["mobile","projects"] verdict, then hand over to the root context resolver.

The pure halves (provider derivation, mode selection, the OTP state machine,
discovery parsing) are unit-tested; 40 -> 83 tests.
---
 web/mobile/src/features/auth/AuthDivider.tsx  |   8 +
 web/mobile/src/features/auth/EmailOtpForm.tsx | 141 ++++++++++++
 .../src/features/auth/EmailPasswordForm.tsx   |  61 +++++
 .../src/features/auth/OidcCallbackScreen.tsx  |  58 +++++
 .../src/features/auth/OidcProviderButtons.tsx |  50 +++++
 web/mobile/src/features/auth/SignInScreen.tsx | 129 +++++------
 .../src/features/auth/SsoDiscoveryForm.tsx    | 120 ++++++++++
 web/mobile/src/features/auth/authStyles.ts    |  10 +
 .../auth/states/AuthMethodsSkeleton.tsx       |   8 +
 .../features/auth/states/NoAuthMethods.tsx    |   6 +
 .../src/features/auth/useAuthSuccess.ts       |  18 ++
 web/mobile/src/lib/auth.ts                    | 103 ---------
 web/mobile/src/lib/auth/config.ts             |  72 ++++++
 web/mobile/src/lib/auth/discover.ts           |  62 +++++
 web/mobile/src/lib/auth/index.ts              | 211 ++++++++++++++++++
 web/mobile/src/lib/auth/otpMachine.ts         | 143 ++++++++++++
 .../pages/auth/callback/[[...provider]].tsx   |  16 ++
 .../src/pages/{auth.tsx => auth/index.tsx}    |   4 +-
 web/mobile/tests/unit/authConfig.test.ts      |  82 +++++++
 web/mobile/tests/unit/authDiscover.test.ts    |  39 ++++
 web/mobile/tests/unit/otpMachine.test.ts      | 154 +++++++++++++
 21 files changed, 1318 insertions(+), 177 deletions(-)
 create mode 100644 web/mobile/src/features/auth/AuthDivider.tsx
 create mode 100644 web/mobile/src/features/auth/EmailOtpForm.tsx
 create mode 100644 web/mobile/src/features/auth/EmailPasswordForm.tsx
 create mode 100644 web/mobile/src/features/auth/OidcCallbackScreen.tsx
 create mode 100644 web/mobile/src/features/auth/OidcProviderButtons.tsx
 create mode 100644 web/mobile/src/features/auth/SsoDiscoveryForm.tsx
 create mode 100644 web/mobile/src/features/auth/authStyles.ts
 create mode 100644 web/mobile/src/features/auth/states/AuthMethodsSkeleton.tsx
 create mode 100644 web/mobile/src/features/auth/states/NoAuthMethods.tsx
 create mode 100644 web/mobile/src/features/auth/useAuthSuccess.ts
 delete mode 100644 web/mobile/src/lib/auth.ts
 create mode 100644 web/mobile/src/lib/auth/config.ts
 create mode 100644 web/mobile/src/lib/auth/discover.ts
 create mode 100644 web/mobile/src/lib/auth/index.ts
 create mode 100644 web/mobile/src/lib/auth/otpMachine.ts
 create mode 100644 web/mobile/src/pages/auth/callback/[[...provider]].tsx
 rename web/mobile/src/pages/{auth.tsx => auth/index.tsx} (65%)
 create mode 100644 web/mobile/tests/unit/authConfig.test.ts
 create mode 100644 web/mobile/tests/unit/authDiscover.test.ts
 create mode 100644 web/mobile/tests/unit/otpMachine.test.ts

diff --git a/web/mobile/src/features/auth/AuthDivider.tsx b/web/mobile/src/features/auth/AuthDivider.tsx
new file mode 100644
index 0000000000..88bfe9909d
--- /dev/null
+++ b/web/mobile/src/features/auth/AuthDivider.tsx
@@ -0,0 +1,8 @@
+/** "or" rule between the social block and the email block. */
+export const AuthDivider = () => (
+    <div className="flex w-full items-center gap-3">
+        <span className="bg-border h-px grow" />
+        <span className="text-muted-foreground text-xs">or</span>
+        <span className="bg-border h-px grow" />
+    </div>
+)
diff --git a/web/mobile/src/features/auth/EmailOtpForm.tsx b/web/mobile/src/features/auth/EmailOtpForm.tsx
new file mode 100644
index 0000000000..41b9c35f9e
--- /dev/null
+++ b/web/mobile/src/features/auth/EmailOtpForm.tsx
@@ -0,0 +1,141 @@
+import {useEffect, useReducer, type FormEvent} from "react"
+
+import {clearEmailCodeAttempt, requestEmailCode, resendEmailCode, submitEmailCode} from "@/lib/auth"
+import {initialOtpState, otpReducer, OTP_RESEND_COOLDOWN_MS} from "@/lib/auth/otpMachine"
+
+import {authFieldClass, authPrimaryButtonClass, authQuietButtonClass} from "./authStyles"
+
+interface EmailOtpFormProps {
+    onSuccess: () => Promise<void>
+}
+
+/** Passwordless sign-in: request a one-time code, then consume it. */
+export const EmailOtpForm = ({onSuccess}: EmailOtpFormProps) => {
+    const [state, dispatch] = useReducer(otpReducer, undefined, () => initialOtpState())
+    const busy = state.phase === "sending" || state.phase === "verifying"
+
+    useEffect(() => {
+        if (!state.resendBlocked) return
+        const timer = setTimeout(() => dispatch({type: "resend-allowed"}), OTP_RESEND_COOLDOWN_MS)
+        return () => clearTimeout(timer)
+    }, [state.resendBlocked])
+
+    const sendCode = async (event: FormEvent<HTMLFormElement>) => {
+        event.preventDefault()
+        if (busy) return
+        dispatch({type: "send"})
+        const outcome = await requestEmailCode(state.email.trim())
+        if (outcome.kind === "ok") dispatch({type: "sent"})
+        else dispatch({type: "failed", message: outcome.message})
+    }
+
+    const verifyCode = async (event: FormEvent<HTMLFormElement>) => {
+        event.preventDefault()
+        if (busy) return
+        dispatch({type: "verify"})
+        const outcome = await submitEmailCode(state.code.trim())
+        if (outcome.kind === "ok") {
+            await clearEmailCodeAttempt()
+            await onSuccess()
+            return
+        }
+        if (outcome.kind === "retry") {
+            dispatch({type: "failed", message: outcome.message})
+            return
+        }
+        await clearEmailCodeAttempt()
+        dispatch({type: "restart", message: outcome.message})
+    }
+
+    const resend = async () => {
+        if (busy || state.resendBlocked) return
+        const outcome = await resendEmailCode()
+        if (outcome.kind === "ok") {
+            dispatch({type: "resent"})
+            return
+        }
+        await clearEmailCodeAttempt()
+        dispatch({type: "restart", message: outcome.message})
+    }
+
+    const useAnotherEmail = async () => {
+        await clearEmailCodeAttempt()
+        dispatch({type: "restart"})
+    }
+
+    const feedback = (
+        <>
+            {state.error ? (
+                <p className="text-destructive text-xs" role="alert">
+                    {state.error}
+                </p>
+            ) : null}
+            {state.notice ? (
+                <p className="text-muted-foreground text-xs" role="status">
+                    {state.notice}
+                </p>
+            ) : null}
+        </>
+    )
+
+    if (state.phase === "email" || state.phase === "sending") {
+        return (
+            <form className="flex w-full flex-col gap-3" onSubmit={sendCode}>
+                <input
+                    type="email"
+                    autoComplete="email"
+                    required
+                    placeholder="Email"
+                    value={state.email}
+                    onChange={(event) => dispatch({type: "edit-email", value: event.target.value})}
+                    className={authFieldClass}
+                />
+                {feedback}
+                <button type="submit" disabled={busy} className={authPrimaryButtonClass}>
+                    {state.phase === "sending" ? "Sending code…" : "Email me a code"}
+                </button>
+            </form>
+        )
+    }
+
+    return (
+        <form className="flex w-full flex-col gap-3" onSubmit={verifyCode}>
+            <p className="text-muted-foreground text-xs">
+                We sent a code to <span className="text-foreground">{state.email}</span>.
+            </p>
+            <input
+                type="text"
+                inputMode="numeric"
+                autoComplete="one-time-code"
+                autoFocus
+                required
+                placeholder="6-digit code"
+                value={state.code}
+                onChange={(event) => dispatch({type: "edit-code", value: event.target.value})}
+                className={`${authFieldClass} tracking-[0.4em]`}
+            />
+            {feedback}
+            <button type="submit" disabled={busy} className={authPrimaryButtonClass}>
+                {state.phase === "verifying" ? "Verifying…" : "Verify code"}
+            </button>
+            <div className="flex flex-col items-center">
+                <button
+                    type="button"
+                    onClick={resend}
+                    disabled={busy || state.resendBlocked}
+                    className={authQuietButtonClass}
+                >
+                    {state.resendBlocked ? "Code sent — wait 60s to resend" : "Resend code"}
+                </button>
+                <button
+                    type="button"
+                    onClick={useAnotherEmail}
+                    disabled={busy}
+                    className={authQuietButtonClass}
+                >
+                    Use a different email
+                </button>
+            </div>
+        </form>
+    )
+}
diff --git a/web/mobile/src/features/auth/EmailPasswordForm.tsx b/web/mobile/src/features/auth/EmailPasswordForm.tsx
new file mode 100644
index 0000000000..a10d0661ce
--- /dev/null
+++ b/web/mobile/src/features/auth/EmailPasswordForm.tsx
@@ -0,0 +1,61 @@
+import {useState, type FormEvent} from "react"
+
+import {signInWithEmailPassword} from "@/lib/auth"
+
+import {authFieldClass, authPrimaryButtonClass} from "./authStyles"
+
+interface EmailPasswordFormProps {
+    onSuccess: () => Promise<void>
+}
+
+export const EmailPasswordForm = ({onSuccess}: EmailPasswordFormProps) => {
+    const [email, setEmail] = useState("")
+    const [password, setPassword] = useState("")
+    const [pending, setPending] = useState(false)
+    const [error, setError] = useState<string | null>(null)
+
+    const onSubmit = async (event: FormEvent<HTMLFormElement>) => {
+        event.preventDefault()
+        if (pending) return
+        setPending(true)
+        setError(null)
+        const outcome = await signInWithEmailPassword(email.trim(), password)
+        if (outcome.kind === "ok") {
+            await onSuccess()
+            return
+        }
+        setPending(false)
+        setError(outcome.kind === "rejected" ? outcome.message : "Something went wrong. Try again.")
+    }
+
+    return (
+        <form className="flex w-full flex-col gap-3" onSubmit={onSubmit}>
+            <input
+                type="email"
+                autoComplete="email"
+                required
+                placeholder="Email"
+                value={email}
+                onChange={(event) => setEmail(event.target.value)}
+                className={authFieldClass}
+            />
+            <input
+                type="password"
+                autoComplete="current-password"
+                required
+                placeholder="Password"
+                value={password}
+                onChange={(event) => setPassword(event.target.value)}
+                className={authFieldClass}
+            />
+            {error ? (
+                <p className="text-destructive text-xs" role="alert">
+                    {error}
+                </p>
+            ) : null}
+            <button type="submit" disabled={pending} className={authPrimaryButtonClass}>
+                {pending ? "Signing in…" : "Sign in"}
+            </button>
+        </form>
+    )
+}
diff --git a/web/mobile/src/features/auth/OidcCallbackScreen.tsx b/web/mobile/src/features/auth/OidcCallbackScreen.tsx
new file mode 100644
index 0000000000..cb2c5e7b85
--- /dev/null
+++ b/web/mobile/src/features/auth/OidcCallbackScreen.tsx
@@ -0,0 +1,58 @@
+import {useEffect, useRef, useState} from "react"
+
+import Link from "next/link"
+import {useRouter} from "next/router"
+
+import {completeOidcSignIn} from "@/lib/auth"
+
+import {useAuthSuccess} from "./useAuthSuccess"
+
+/**
+ * Landing for an OIDC redirect the mobile app started. The provider redirected
+ * to the desktop `/auth/callback/<id>` (the only registered URI) and the device
+ * gate forwarded it here with the query intact; signInAndUp reads the OAuth
+ * state from the same-origin sessionStorage and exchanges the code.
+ */
+export const OidcCallbackScreen = () => {
+    const router = useRouter()
+    const onSuccess = useAuthSuccess()
+    const started = useRef(false)
+    const [error, setError] = useState<string | null>(null)
+
+    useEffect(() => {
+        // Wait for the query so a missing code reads as "not ready", not "failed".
+        if (!router.isReady || started.current) return
+        started.current = true
+
+        if (!router.query.code && !router.query.state) {
+            void router.replace("/auth")
+            return
+        }
+
+        void (async () => {
+            const outcome = await completeOidcSignIn()
+            if (outcome.kind === "ok") {
+                await onSuccess()
+                return
+            }
+            setError(outcome.message)
+        })()
+    }, [router, router.isReady, onSuccess])
+
+    return (
+        <div className="bg-background text-foreground flex min-h-dvh flex-col items-center justify-center gap-3 p-6 text-center">
+            {error ? (
+                <>
+                    <p className="text-destructive text-xs" role="alert">
+                        {error}
+                    </p>
+                    <Link href="/auth" className="-m-3 p-3 text-xs underline underline-offset-4">
+                        Back to sign in
+                    </Link>
+                </>
+            ) : (
+                <p className="text-muted-foreground text-xs">Finishing sign-in…</p>
+            )}
+        </div>
+    )
+}
diff --git a/web/mobile/src/features/auth/OidcProviderButtons.tsx b/web/mobile/src/features/auth/OidcProviderButtons.tsx
new file mode 100644
index 0000000000..6ce12c50ae
--- /dev/null
+++ b/web/mobile/src/features/auth/OidcProviderButtons.tsx
@@ -0,0 +1,50 @@
+import {useState} from "react"
+
+import {startOidcSignIn, type OidcProvider} from "@/lib/auth"
+
+import {authPrimaryButtonClass} from "./authStyles"
+
+interface OidcProviderButtonsProps {
+    providers: OidcProvider[]
+}
+
+/** One button per configured provider; clicking leaves for the provider. */
+export const OidcProviderButtons = ({providers}: OidcProviderButtonsProps) => {
+    const [redirecting, setRedirecting] = useState<string | null>(null)
+    const [error, setError] = useState<string | null>(null)
+
+    const start = async (providerId: string) => {
+        if (redirecting) return
+        setRedirecting(providerId)
+        setError(null)
+        // Resolves only on failure — success navigates away.
+        await startOidcSignIn(providerId)
+        setRedirecting(null)
+        setError("Could not reach that provider. Try again.")
+    }
+
+    if (providers.length === 0) return null
+
+    return (
+        <div className="flex w-full flex-col gap-2">
+            {providers.map((provider) => (
+                <button
+                    key={provider.id}
+                    type="button"
+                    onClick={() => start(provider.id)}
+                    disabled={Boolean(redirecting)}
+                    className={authPrimaryButtonClass}
+                >
+                    {redirecting === provider.id
+                        ? `Opening ${provider.label}…`
+                        : `Continue with ${provider.label}`}
+                </button>
+            ))}
+            {error ? (
+                <p className="text-destructive text-xs" role="alert">
+                    {error}
+                </p>
+            ) : null}
+        </div>
+    )
+}
diff --git a/web/mobile/src/features/auth/SignInScreen.tsx b/web/mobile/src/features/auth/SignInScreen.tsx
index 8f93c90217..cbf186002e 100644
--- a/web/mobile/src/features/auth/SignInScreen.tsx
+++ b/web/mobile/src/features/auth/SignInScreen.tsx
@@ -1,89 +1,74 @@
-import {useEffect, useState, type FormEvent} from "react"
+import {useEffect, useState} from "react"
 
-import {useRouter} from "next/router"
+import {
+    getEmailSignInMode,
+    isOidcEnabled,
+    listOidcProviders,
+    type EmailSignInMode,
+    type OidcProvider,
+} from "@/lib/auth"
 
-import {getEmailSignInMode, signInWithEmailPassword, type EmailSignInMode} from "@/lib/auth"
-import {queryClient} from "@/lib/queryClient"
+import {AuthDivider} from "./AuthDivider"
+import {EmailOtpForm} from "./EmailOtpForm"
+import {EmailPasswordForm} from "./EmailPasswordForm"
+import {OidcProviderButtons} from "./OidcProviderButtons"
+import {SsoDiscoveryForm} from "./SsoDiscoveryForm"
+import {AuthMethodsSkeleton} from "./states/AuthMethodsSkeleton"
+import {NoAuthMethods} from "./states/NoAuthMethods"
+import {useAuthSuccess} from "./useAuthSuccess"
 
-/** Raw email/password sign-in (auth-lite). OIDC/social stays a desktop flow. */
-export const SignInScreen = () => {
-    const router = useRouter()
-    // Mode reads window.__env — resolve after mount so SSR markup never differs.
-    const [mode, setMode] = useState<EmailSignInMode | null>(null)
-    useEffect(() => setMode(getEmailSignInMode()), [])
-
-    const [email, setEmail] = useState("")
-    const [password, setPassword] = useState("")
-    const [pending, setPending] = useState(false)
-    const [error, setError] = useState<string | null>(null)
+interface ResolvedMethods {
+    mode: EmailSignInMode
+    providers: OidcProvider[]
+    /** Org-SSO discovery is worth offering whenever the deployment enables OIDC. */
+    ssoDiscovery: boolean
+}
 
-    const onSubmit = async (event: FormEvent<HTMLFormElement>) => {
-        event.preventDefault()
-        if (pending) return
-        setPending(true)
-        setError(null)
-        const outcome = await signInWithEmailPassword(email.trim(), password)
-        if (outcome.kind === "ok") {
-            // Drop the cached unauthenticated verdict before the resolver reruns.
-            await queryClient.invalidateQueries({queryKey: ["mobile", "projects"]})
-            void router.replace("/")
-            return
-        }
-        setPending(false)
-        setError(outcome.kind === "rejected" ? outcome.message : "Something went wrong. Try again.")
-    }
+/** Every method this deployment enables: password OR one-time code, social, org SSO. */
+export const SignInScreen = () => {
+    const onSuccess = useAuthSuccess()
+    // Methods read window.__env — resolve after mount so SSR markup never differs.
+    const [methods, setMethods] = useState<ResolvedMethods | null>(null)
+    useEffect(
+        () =>
+            setMethods({
+                mode: getEmailSignInMode(),
+                providers: listOidcProviders(),
+                ssoDiscovery: isOidcEnabled(),
+            }),
+        [],
+    )
 
     let body
-    if (mode === null) {
-        body = <p className="text-muted-foreground text-center text-xs">Loading…</p>
-    } else if (mode !== "password") {
-        body = (
-            <p className="text-muted-foreground text-center text-xs">
-                {mode === "otp"
-                    ? "Email code sign-in is not available here."
-                    : "Email sign-in is disabled on this deployment."}
-            </p>
-        )
+    if (methods === null) {
+        body = <AuthMethodsSkeleton />
+    } else if (
+        methods.mode === "disabled" &&
+        methods.providers.length === 0 &&
+        !methods.ssoDiscovery
+    ) {
+        body = <NoAuthMethods />
     } else {
+        const emailBlock =
+            methods.mode === "password" ? (
+                <EmailPasswordForm onSuccess={onSuccess} />
+            ) : methods.mode === "otp" ? (
+                <EmailOtpForm onSuccess={onSuccess} />
+            ) : null
         body = (
-            <form className="flex w-full flex-col gap-3" onSubmit={onSubmit}>
-                <input
-                    type="email"
-                    autoComplete="email"
-                    required
-                    placeholder="Email"
-                    value={email}
-                    onChange={(event) => setEmail(event.target.value)}
-                    className="border-border bg-background rounded-md border px-3 py-2 text-base"
-                />
-                <input
-                    type="password"
-                    autoComplete="current-password"
-                    required
-                    placeholder="Password"
-                    value={password}
-                    onChange={(event) => setPassword(event.target.value)}
-                    className="border-border bg-background rounded-md border px-3 py-2 text-base"
-                />
-                {error ? <p className="text-destructive text-xs">{error}</p> : null}
-                <button
-                    type="submit"
-                    disabled={pending}
-                    className="border-border min-h-11 rounded-md border px-3 py-2 text-sm disabled:opacity-50"
-                >
-                    {pending ? "Signing in…" : "Sign in"}
-                </button>
-            </form>
+            <div className="flex w-full flex-col gap-4">
+                <OidcProviderButtons providers={methods.providers} />
+                {methods.providers.length > 0 && emailBlock ? <AuthDivider /> : null}
+                {emailBlock}
+                {methods.ssoDiscovery ? <SsoDiscoveryForm /> : null}
+            </div>
         )
     }
 
     return (
         <div className="bg-background text-foreground flex min-h-dvh flex-col items-center justify-center gap-4 p-6">
             <p className="text-sm font-medium">Sign in to Agenta</p>
-            {body}
-            <p className="text-muted-foreground text-center text-xs">
-                For SSO or social sign-in, use the desktop app.
-            </p>
+            <div className="flex w-full max-w-sm flex-col items-center gap-4">{body}</div>
         </div>
     )
 }
diff --git a/web/mobile/src/features/auth/SsoDiscoveryForm.tsx b/web/mobile/src/features/auth/SsoDiscoveryForm.tsx
new file mode 100644
index 0000000000..85de02ea7d
--- /dev/null
+++ b/web/mobile/src/features/auth/SsoDiscoveryForm.tsx
@@ -0,0 +1,120 @@
+import {useState, type FormEvent} from "react"
+
+import {startOidcSignIn} from "@/lib/auth"
+import {discoverSsoProviders, type DiscoveredSsoProvider} from "@/lib/auth/discover"
+
+import {authFieldClass, authPrimaryButtonClass, authQuietButtonClass} from "./authStyles"
+
+type Phase = "idle" | "asking" | "checking" | "results"
+
+/**
+ * Organization SSO: ask for the work email, let the backend name the org's
+ * providers, then run the same redirect flow as the social buttons.
+ */
+export const SsoDiscoveryForm = () => {
+    const [phase, setPhase] = useState<Phase>("idle")
+    const [email, setEmail] = useState("")
+    const [providers, setProviders] = useState<DiscoveredSsoProvider[]>([])
+    const [error, setError] = useState<string | null>(null)
+    const [redirecting, setRedirecting] = useState<string | null>(null)
+
+    const check = async (event: FormEvent<HTMLFormElement>) => {
+        event.preventDefault()
+        if (phase === "checking") return
+        setPhase("checking")
+        setError(null)
+        const result = await discoverSsoProviders(email.trim())
+        if (result.kind === "failed") {
+            setPhase("asking")
+            setError(result.message)
+            return
+        }
+        if (result.providers.length === 0) {
+            setPhase("asking")
+            setError("No SSO is configured for that email.")
+            return
+        }
+        setProviders(result.providers)
+        setPhase("results")
+    }
+
+    const start = async (thirdPartyId: string) => {
+        if (redirecting) return
+        setRedirecting(thirdPartyId)
+        setError(null)
+        // Resolves only on failure — success navigates away.
+        await startOidcSignIn(thirdPartyId)
+        setRedirecting(null)
+        setError("Could not reach that provider. Try again.")
+    }
+
+    if (phase === "idle") {
+        return (
+            <button
+                type="button"
+                onClick={() => setPhase("asking")}
+                className={authQuietButtonClass}
+            >
+                Sign in with organization SSO
+            </button>
+        )
+    }
+
+    if (phase === "results") {
+        return (
+            <div className="flex w-full flex-col gap-2">
+                {providers.map((provider) => (
+                    <button
+                        key={provider.id}
+                        type="button"
+                        onClick={() => start(provider.thirdPartyId)}
+                        disabled={Boolean(redirecting)}
+                        className={authPrimaryButtonClass}
+                    >
+                        {redirecting === provider.thirdPartyId
+                            ? `Opening ${provider.label}…`
+                            : `Continue with SSO (${provider.label})`}
+                    </button>
+                ))}
+                {error ? (
+                    <p className="text-destructive text-xs" role="alert">
+                        {error}
+                    </p>
+                ) : null}
+                <button
+                    type="button"
+                    onClick={() => setPhase("asking")}
+                    className={authQuietButtonClass}
+                >
+                    Use a different email
+                </button>
+            </div>
+        )
+    }
+
+    return (
+        <form className="flex w-full flex-col gap-3" onSubmit={check}>
+            <input
+                type="email"
+                autoComplete="email"
+                required
+                placeholder="Work email"
+                value={email}
+                onChange={(event) => setEmail(event.target.value)}
+                className={authFieldClass}
+            />
+            {error ? (
+                <p className="text-destructive text-xs" role="alert">
+                    {error}
+                </p>
+            ) : null}
+            <button
+                type="submit"
+                disabled={phase === "checking"}
+                className={authPrimaryButtonClass}
+            >
+                {phase === "checking" ? "Checking…" : "Continue with SSO"}
+            </button>
+        </form>
+    )
+}
diff --git a/web/mobile/src/features/auth/authStyles.ts b/web/mobile/src/features/auth/authStyles.ts
new file mode 100644
index 0000000000..21d05f6071
--- /dev/null
+++ b/web/mobile/src/features/auth/authStyles.ts
@@ -0,0 +1,10 @@
+/** Shared raw-element classes for the sign-in surfaces (semantic tokens only). */
+
+export const authFieldClass =
+    "border-border bg-background rounded-md border px-3 py-2 text-base disabled:opacity-50"
+
+export const authPrimaryButtonClass =
+    "border-border min-h-11 rounded-md border px-3 py-2 text-sm disabled:opacity-50"
+
+export const authQuietButtonClass =
+    "text-muted-foreground min-h-11 px-3 py-2 text-xs underline underline-offset-4 disabled:opacity-50"
diff --git a/web/mobile/src/features/auth/states/AuthMethodsSkeleton.tsx b/web/mobile/src/features/auth/states/AuthMethodsSkeleton.tsx
new file mode 100644
index 0000000000..8bd4422fe2
--- /dev/null
+++ b/web/mobile/src/features/auth/states/AuthMethodsSkeleton.tsx
@@ -0,0 +1,8 @@
+/** Mirrors the resolved layout (two buttons + a field) so nothing shifts. */
+export const AuthMethodsSkeleton = () => (
+    <div className="flex w-full flex-col gap-3" aria-hidden>
+        <div className="bg-muted h-11 w-full animate-pulse rounded-md" />
+        <div className="bg-muted h-11 w-full animate-pulse rounded-md" />
+        <div className="bg-muted h-11 w-full animate-pulse rounded-md" />
+    </div>
+)
diff --git a/web/mobile/src/features/auth/states/NoAuthMethods.tsx b/web/mobile/src/features/auth/states/NoAuthMethods.tsx
new file mode 100644
index 0000000000..fd768092e7
--- /dev/null
+++ b/web/mobile/src/features/auth/states/NoAuthMethods.tsx
@@ -0,0 +1,6 @@
+/** Every method is disabled by env — say so instead of showing an empty card. */
+export const NoAuthMethods = () => (
+    <p className="text-muted-foreground text-center text-xs">
+        No sign-in method is enabled on this deployment. Contact your administrator.
+    </p>
+)
diff --git a/web/mobile/src/features/auth/useAuthSuccess.ts b/web/mobile/src/features/auth/useAuthSuccess.ts
new file mode 100644
index 0000000000..1d13e8303f
--- /dev/null
+++ b/web/mobile/src/features/auth/useAuthSuccess.ts
@@ -0,0 +1,18 @@
+import {useCallback} from "react"
+
+import {useRouter} from "next/router"
+
+import {queryClient} from "@/lib/queryClient"
+
+/**
+ * Where every successful sign-in lands, whatever the route (password, OTP,
+ * OIDC): drop the cached unauthenticated verdict so the root context resolver
+ * re-fetches, then hand over to it.
+ */
+export function useAuthSuccess() {
+    const router = useRouter()
+    return useCallback(async () => {
+        await queryClient.invalidateQueries({queryKey: ["mobile", "projects"]})
+        await router.replace("/")
+    }, [router])
+}
diff --git a/web/mobile/src/lib/auth.ts b/web/mobile/src/lib/auth.ts
deleted file mode 100644
index 8486519c61..0000000000
--- a/web/mobile/src/lib/auth.ts
+++ /dev/null
@@ -1,103 +0,0 @@
-import SuperTokens from "supertokens-web-js"
-import EmailPassword from "supertokens-web-js/recipe/emailpassword"
-import Session from "supertokens-web-js/recipe/session"
-
-import {getApiUrl, getEnv} from "./env"
-
-/**
- * Headless SuperTokens client (supertokens-web-js — same 0.16.x the desktop's
- * supertokens-auth-react wraps). appInfo mirrors web/oss/src/config/appInfo.ts
- * exactly (apiDomain + "/api/auth"), so both apps share the one cookie session
- * against the same backend.
- */
-let initialized = false
-
-export function ensureAuthInit(): void {
-    if (initialized || typeof window === "undefined") return
-    SuperTokens.init({
-        appInfo: {
-            appName: "agenta",
-            apiDomain: getApiUrl(),
-            apiBasePath: "/api/auth",
-        },
-        recipeList: [Session.init(), EmailPassword.init()],
-    })
-    initialized = true
-}
-
-/** OIDC client-id env keys the desktop's getEffectiveAuthConfig checks. */
-const OIDC_CLIENT_ID_KEYS = [
-    "NEXT_PUBLIC_AGENTA_AUTH_GOOGLE_OAUTH_CLIENT_ID",
-    "NEXT_PUBLIC_AGENTA_AUTH_GOOGLE_WORKSPACES_OAUTH_CLIENT_ID",
-    "NEXT_PUBLIC_AGENTA_AUTH_GITHUB_OAUTH_CLIENT_ID",
-    "NEXT_PUBLIC_AGENTA_AUTH_FACEBOOK_OAUTH_CLIENT_ID",
-    "NEXT_PUBLIC_AGENTA_AUTH_APPLE_OAUTH_CLIENT_ID",
-    "NEXT_PUBLIC_AGENTA_AUTH_DISCORD_OAUTH_CLIENT_ID",
-    "NEXT_PUBLIC_AGENTA_AUTH_TWITTER_OAUTH_CLIENT_ID",
-    "NEXT_PUBLIC_AGENTA_AUTH_GITLAB_OAUTH_CLIENT_ID",
-    "NEXT_PUBLIC_AGENTA_AUTH_BITBUCKET_OAUTH_CLIENT_ID",
-    "NEXT_PUBLIC_AGENTA_AUTH_LINKEDIN_OAUTH_CLIENT_ID",
-    "NEXT_PUBLIC_AGENTA_AUTH_OKTA_OAUTH_CLIENT_ID",
-    "NEXT_PUBLIC_AGENTA_AUTH_AZURE_AD_OAUTH_CLIENT_ID",
-    "NEXT_PUBLIC_AGENTA_AUTH_BOXY_SAML_OAUTH_CLIENT_ID",
-]
-
-export type EmailSignInMode = "password" | "otp" | "disabled"
-
-/**
- * Effective email-auth mode, mirroring the desktop's getEffectiveAuthConfig
- * (web/oss/src/lib/helpers/dynamicEnv.ts): NEXT_PUBLIC_AGENTA_AUTHN_EMAIL
- * wins; unset defaults to "password" only when no OIDC provider is enabled.
- * Mobile can act on "password" only — "otp" and SSO stay desktop flows.
- */
-export function getEmailSignInMode(): EmailSignInMode {
-    const oidcEnabled =
-        getEnv("NEXT_PUBLIC_AGENTA_AUTH_OIDC_ENABLED").toLowerCase() === "true" ||
-        OIDC_CLIENT_ID_KEYS.some((key) => Boolean(getEnv(key)))
-    const authnEmail = getEnv("NEXT_PUBLIC_AGENTA_AUTHN_EMAIL") || (oidcEnabled ? "" : "password")
-    if (authnEmail === "password" || authnEmail === "otp") return authnEmail
-    return "disabled"
-}
-
-export type SignInOutcome = {kind: "ok"} | {kind: "rejected"; message: string} | {kind: "error"}
-
-export async function signInWithEmailPassword(
-    email: string,
-    password: string,
-): Promise<SignInOutcome> {
-    ensureAuthInit()
-    try {
-        const result = await EmailPassword.signIn({
-            formFields: [
-                {id: "email", value: email},
-                {id: "password", value: password},
-            ],
-        })
-        if (result.status === "OK") return {kind: "ok"}
-        if (result.status === "WRONG_CREDENTIALS_ERROR")
-            return {kind: "rejected", message: "Incorrect email or password."}
-        if (result.status === "FIELD_ERROR")
-            return {
-                kind: "rejected",
-                message: result.formFields[0]?.error ?? "Invalid email or password.",
-            }
-        return {kind: "rejected", message: result.reason}
-    } catch {
-        return {kind: "error"}
-    }
-}
-
-/**
- * Attempt a cookie-based session refresh. Resolves false when there is no
- * refresh token or the backend rejects it — the caller's signed-out verdict
- * stands. Never throws (network failure counts as "not refreshed").
- */
-export async function tryRefreshSession(): Promise<boolean> {
-    if (typeof window === "undefined") return false
-    ensureAuthInit()
-    try {
-        return await Session.attemptRefreshingSession()
-    } catch {
-        return false
-    }
-}
diff --git a/web/mobile/src/lib/auth/config.ts b/web/mobile/src/lib/auth/config.ts
new file mode 100644
index 0000000000..0952deb586
--- /dev/null
+++ b/web/mobile/src/lib/auth/config.ts
@@ -0,0 +1,72 @@
+/**
+ * Pure auth-configuration derivation. Mirrors the desktop's
+ * getEffectiveAuthConfig (web/oss/src/lib/helpers/dynamicEnv.ts) and the
+ * provider metadata table in web/oss/src/pages/auth/[[...path]].tsx, so both
+ * apps offer exactly the methods a deployment enabled.
+ *
+ * No SuperTokens import on purpose: this is the unit-tested half.
+ */
+import {getEnv} from "../env"
+
+export type EnvReader = (key: string) => string
+
+export type EmailSignInMode = "password" | "otp" | "disabled"
+
+export interface OidcProvider {
+    /** SuperTokens thirdPartyId. */
+    id: string
+    label: string
+}
+
+/**
+ * Provider id → client-id env key → label. Order matches the desktop list so
+ * both apps present providers identically.
+ */
+export const OIDC_PROVIDER_META: readonly {id: string; envKey: string; label: string}[] = [
+    {id: "google", envKey: "NEXT_PUBLIC_AGENTA_AUTH_GOOGLE_OAUTH_CLIENT_ID", label: "Google"},
+    {
+        id: "google-workspaces",
+        envKey: "NEXT_PUBLIC_AGENTA_AUTH_GOOGLE_WORKSPACES_OAUTH_CLIENT_ID",
+        label: "Google Workspaces",
+    },
+    {id: "github", envKey: "NEXT_PUBLIC_AGENTA_AUTH_GITHUB_OAUTH_CLIENT_ID", label: "GitHub"},
+    {id: "facebook", envKey: "NEXT_PUBLIC_AGENTA_AUTH_FACEBOOK_OAUTH_CLIENT_ID", label: "Facebook"},
+    {id: "apple", envKey: "NEXT_PUBLIC_AGENTA_AUTH_APPLE_OAUTH_CLIENT_ID", label: "Apple"},
+    {id: "discord", envKey: "NEXT_PUBLIC_AGENTA_AUTH_DISCORD_OAUTH_CLIENT_ID", label: "Discord"},
+    {id: "twitter", envKey: "NEXT_PUBLIC_AGENTA_AUTH_TWITTER_OAUTH_CLIENT_ID", label: "X"},
+    {id: "gitlab", envKey: "NEXT_PUBLIC_AGENTA_AUTH_GITLAB_OAUTH_CLIENT_ID", label: "GitLab"},
+    {
+        id: "bitbucket",
+        envKey: "NEXT_PUBLIC_AGENTA_AUTH_BITBUCKET_OAUTH_CLIENT_ID",
+        label: "Bitbucket",
+    },
+    {id: "linkedin", envKey: "NEXT_PUBLIC_AGENTA_AUTH_LINKEDIN_OAUTH_CLIENT_ID", label: "LinkedIn"},
+    {id: "okta", envKey: "NEXT_PUBLIC_AGENTA_AUTH_OKTA_OAUTH_CLIENT_ID", label: "Okta"},
+    {id: "azure-ad", envKey: "NEXT_PUBLIC_AGENTA_AUTH_AZURE_AD_OAUTH_CLIENT_ID", label: "Azure AD"},
+    {id: "boxy-saml", envKey: "NEXT_PUBLIC_AGENTA_AUTH_BOXY_SAML_OAUTH_CLIENT_ID", label: "SAML"},
+]
+
+/** A provider is offered iff the deployment configured its OAuth client id. */
+export function listOidcProviders(read: EnvReader = getEnv): OidcProvider[] {
+    return OIDC_PROVIDER_META.filter((provider) => Boolean(read(provider.envKey))).map(
+        ({id, label}) => ({id, label}),
+    )
+}
+
+/** Desktop parity: the OIDC block is on when flagged OR any client id is set. */
+export function isOidcEnabled(read: EnvReader = getEnv): boolean {
+    if (read("NEXT_PUBLIC_AGENTA_AUTH_OIDC_ENABLED").toLowerCase() === "true") return true
+    return listOidcProviders(read).length > 0
+}
+
+/**
+ * Effective email-auth mode. NEXT_PUBLIC_AGENTA_AUTHN_EMAIL wins; unset
+ * defaults to "password" only when no OIDC provider is enabled (otherwise the
+ * deployment is SSO-only and email must stay hidden).
+ */
+export function getEmailSignInMode(read: EnvReader = getEnv): EmailSignInMode {
+    const authnEmail =
+        read("NEXT_PUBLIC_AGENTA_AUTHN_EMAIL") || (isOidcEnabled(read) ? "" : "password")
+    if (authnEmail === "password" || authnEmail === "otp") return authnEmail
+    return "disabled"
+}
diff --git a/web/mobile/src/lib/auth/discover.ts b/web/mobile/src/lib/auth/discover.ts
new file mode 100644
index 0000000000..fc1c1124fa
--- /dev/null
+++ b/web/mobile/src/lib/auth/discover.ts
@@ -0,0 +1,62 @@
+/**
+ * Organization SSO discovery (EE). The env flags only describe the deployment's
+ * *social* providers; an org's own OIDC/SAML connection is keyed to the user's
+ * email domain and only the backend knows it. Same endpoint and payload shape
+ * the desktop uses (web/oss/src/pages/auth/[[...path]].tsx → /auth/discover).
+ */
+import {getApiUrl} from "../env"
+
+export interface DiscoveredSsoProvider {
+    id: string
+    /** SuperTokens thirdPartyId, e.g. "sso:acme". */
+    thirdPartyId: string
+    /** Human label — the org slug the desktop shows. */
+    label: string
+}
+
+/** Desktop parity: label an `sso:<slug>` id by its slug, else by the record's. */
+export function formatSsoLabel(slug: string, thirdPartyId: string): string {
+    return thirdPartyId.startsWith("sso:") ? thirdPartyId.replace(/^sso:/, "") : slug
+}
+
+/** Pull the usable SSO providers out of a /auth/discover payload. */
+export function parseDiscoveredSso(payload: unknown): DiscoveredSsoProvider[] {
+    const methods = (payload as {methods?: {sso?: {providers?: unknown}}} | null)?.methods
+    const providers = methods?.sso?.providers
+    if (!Array.isArray(providers)) return []
+    return providers.flatMap((entry) => {
+        const record = entry as {id?: unknown; slug?: unknown; third_party_id?: unknown}
+        // No third_party_id ⇒ nothing to hand SuperTokens; drop it.
+        if (typeof record.id !== "string" || typeof record.third_party_id !== "string") return []
+        const slug = typeof record.slug === "string" ? record.slug : record.third_party_id
+        return [
+            {
+                id: record.id,
+                thirdPartyId: record.third_party_id,
+                label: formatSsoLabel(slug, record.third_party_id),
+            },
+        ]
+    })
+}
+
+export type SsoDiscoveryResult =
+    | {kind: "ok"; providers: DiscoveredSsoProvider[]}
+    | {kind: "failed"; message: string}
+
+/** Ask the backend which org SSO connections accept `email`. */
+export async function discoverSsoProviders(email: string): Promise<SsoDiscoveryResult> {
+    try {
+        const response = await fetch(`${getApiUrl()}/auth/discover`, {
+            method: "POST",
+            headers: {"Content-Type": "application/json"},
+            credentials: "include",
+            body: JSON.stringify({email}),
+        })
+        // 404 on OSS (the endpoint is EE-only) reads as "no SSO", not an error.
+        if (response.status === 404) return {kind: "ok", providers: []}
+        if (!response.ok) return {kind: "failed", message: "Could not check SSO. Try again."}
+        return {kind: "ok", providers: parseDiscoveredSso(await response.json())}
+    } catch {
+        return {kind: "failed", message: "Could not check SSO. Try again."}
+    }
+}
diff --git a/web/mobile/src/lib/auth/index.ts b/web/mobile/src/lib/auth/index.ts
new file mode 100644
index 0000000000..e5c8686f7d
--- /dev/null
+++ b/web/mobile/src/lib/auth/index.ts
@@ -0,0 +1,211 @@
+import {
+    MOBILE_AUTH_CALLBACK_COOKIE,
+    MOBILE_AUTH_CALLBACK_MAX_AGE,
+} from "@agenta/shared/utils/mobileGate"
+import SuperTokens from "supertokens-web-js"
+import EmailPassword from "supertokens-web-js/recipe/emailpassword"
+import Passwordless from "supertokens-web-js/recipe/passwordless"
+import Session from "supertokens-web-js/recipe/session"
+import ThirdParty from "supertokens-web-js/recipe/thirdparty"
+
+import {getApiUrl, getEnv} from "../env"
+
+import {
+    describeConsumeCode,
+    describeCreateCode,
+    describeResendCode,
+    type OtpOutcome,
+} from "./otpMachine"
+
+export {getEmailSignInMode, listOidcProviders, isOidcEnabled, OIDC_PROVIDER_META} from "./config"
+export type {EmailSignInMode, OidcProvider} from "./config"
+
+/**
+ * Headless SuperTokens client (supertokens-web-js — same 0.16.x the desktop's
+ * supertokens-auth-react wraps). appInfo mirrors web/oss/src/config/appInfo.ts
+ * exactly (apiDomain + "/api/auth"), so both apps share the one cookie session
+ * against the same backend.
+ *
+ * All four recipes are registered unconditionally: unlike the desktop's
+ * auth-react config, recipe registration here only decides which client
+ * functions exist, never what the UI shows — the sign-in screen gates that on
+ * the env flags (./config).
+ */
+let initialized = false
+
+export function ensureAuthInit(): void {
+    if (initialized || typeof window === "undefined") return
+    SuperTokens.init({
+        appInfo: {
+            appName: "agenta",
+            apiDomain: getApiUrl(),
+            apiBasePath: "/api/auth",
+        },
+        recipeList: [Session.init(), EmailPassword.init(), Passwordless.init(), ThirdParty.init()],
+    })
+    initialized = true
+}
+
+export type SignInOutcome = {kind: "ok"} | {kind: "rejected"; message: string} | {kind: "error"}
+
+export async function signInWithEmailPassword(
+    email: string,
+    password: string,
+): Promise<SignInOutcome> {
+    ensureAuthInit()
+    try {
+        const result = await EmailPassword.signIn({
+            formFields: [
+                {id: "email", value: email},
+                {id: "password", value: password},
+            ],
+        })
+        if (result.status === "OK") return {kind: "ok"}
+        if (result.status === "WRONG_CREDENTIALS_ERROR")
+            return {kind: "rejected", message: "Incorrect email or password."}
+        if (result.status === "FIELD_ERROR")
+            return {
+                kind: "rejected",
+                message: result.formFields[0]?.error ?? "Invalid email or password.",
+            }
+        return {kind: "rejected", message: result.reason}
+    } catch {
+        return {kind: "error"}
+    }
+}
+
+/* ------------------------------- email OTP -------------------------------- */
+
+/** Send a one-time code to `email` and open a login attempt. */
+export async function requestEmailCode(
+    email: string,
+): Promise<{kind: "ok"} | {kind: "failed"; message: string}> {
+    ensureAuthInit()
+    try {
+        return describeCreateCode(await Passwordless.createCode({email}))
+    } catch {
+        return describeCreateCode(null)
+    }
+}
+
+/** Re-send the code for the open attempt. */
+export async function resendEmailCode(): Promise<
+    {kind: "ok"} | {kind: "restart"; message: string}
+> {
+    ensureAuthInit()
+    try {
+        return describeResendCode(await Passwordless.resendCode())
+    } catch {
+        return describeResendCode(null)
+    }
+}
+
+/** Exchange the typed code for a session. */
+export async function submitEmailCode(code: string): Promise<OtpOutcome> {
+    ensureAuthInit()
+    try {
+        return describeConsumeCode(await Passwordless.consumeCode({userInputCode: code}))
+    } catch {
+        return describeConsumeCode(null)
+    }
+}
+
+/** Drop the open attempt (back-to-email, or after an unrecoverable failure). */
+export async function clearEmailCodeAttempt(): Promise<void> {
+    ensureAuthInit()
+    try {
+        await Passwordless.clearLoginAttemptInfo()
+    } catch {
+        // Nothing to clear is not an error.
+    }
+}
+
+/* ------------------------------ OIDC / social ----------------------------- */
+
+/**
+ * Web origin the providers' redirect URIs are registered against. Byte-identical
+ * to the desktop's expression (web/oss/src/components/pages/auth/SocialAuth) —
+ * the redirect URI we hand SuperTokens must match the registered one exactly.
+ */
+function getRegisteredWebUrl(): string {
+    return getEnv("NEXT_PUBLIC_AGENTA_WEB_URL") || getEnv("NEXT_PUBLIC_AGENTA_API_URL")
+}
+
+/** The ONE redirect URI registered with each provider — always the desktop path. */
+export function providerRedirectUri(providerId: string): string {
+    return `${getRegisteredWebUrl()}/auth/callback/${providerId}`
+}
+
+/** Where the mobile app wants to resume once the code is exchanged. */
+export function mobileCallbackUri(providerId: string): string {
+    return `${getRegisteredWebUrl()}/m/auth/callback/${providerId}`
+}
+
+function markMobileAuthCallback(): void {
+    document.cookie = `${MOBILE_AUTH_CALLBACK_COOKIE}=1; path=/; max-age=${MOBILE_AUTH_CALLBACK_MAX_AGE}; samesite=lax`
+}
+
+export function clearMobileAuthCallbackMark(): void {
+    if (typeof document === "undefined") return
+    document.cookie = `${MOBILE_AUTH_CALLBACK_COOKIE}=; path=/; max-age=0; samesite=lax`
+}
+
+/**
+ * Start an OIDC sign-in. The provider redirects to the registered DESKTOP URI;
+ * the cookie tells the desktop gate to forward that landing to /m/auth/callback,
+ * where completeOidcSignIn finishes the exchange against the same-origin
+ * sessionStorage OAuth state. No new redirect URI has to be registered.
+ */
+export async function startOidcSignIn(providerId: string): Promise<{kind: "error"} | never> {
+    ensureAuthInit()
+    try {
+        const authUrl = await ThirdParty.getAuthorisationURLWithQueryParamsAndSetState({
+            thirdPartyId: providerId,
+            frontendRedirectURI: mobileCallbackUri(providerId),
+            redirectURIOnProviderDashboard: providerRedirectUri(providerId),
+        })
+        markMobileAuthCallback()
+        window.location.assign(authUrl)
+        return await new Promise<never>(() => {
+            /* navigating away — never settles */
+        })
+    } catch {
+        clearMobileAuthCallbackMark()
+        return {kind: "error"}
+    }
+}
+
+export type OidcCallbackOutcome = {kind: "ok"} | {kind: "failed"; message: string}
+
+/** Finish the redirect flow: verify state, exchange the code, set the session. */
+export async function completeOidcSignIn(): Promise<OidcCallbackOutcome> {
+    ensureAuthInit()
+    clearMobileAuthCallbackMark()
+    try {
+        const result = await ThirdParty.signInAndUp()
+        if (result.status === "OK") return {kind: "ok"}
+        if (result.status === "SIGN_IN_UP_NOT_ALLOWED")
+            return {kind: "failed", message: result.reason}
+        return {
+            kind: "failed",
+            message: "That provider did not share an email. Try another sign-in method.",
+        }
+    } catch {
+        return {kind: "failed", message: "Sign-in could not be completed. Try again."}
+    }
+}
+
+/**
+ * Attempt a cookie-based session refresh. Resolves false when there is no
+ * refresh token or the backend rejects it — the caller's signed-out verdict
+ * stands. Never throws (network failure counts as "not refreshed").
+ */
+export async function tryRefreshSession(): Promise<boolean> {
+    if (typeof window === "undefined") return false
+    ensureAuthInit()
+    try {
+        return await Session.attemptRefreshingSession()
+    } catch {
+        return false
+    }
+}
diff --git a/web/mobile/src/lib/auth/otpMachine.ts b/web/mobile/src/lib/auth/otpMachine.ts
new file mode 100644
index 0000000000..5a7a66464a
--- /dev/null
+++ b/web/mobile/src/lib/auth/otpMachine.ts
@@ -0,0 +1,143 @@
+/**
+ * Pure state machine + status mapping for the passwordless (email OTP) flow.
+ *
+ * Kept free of SuperTokens imports so the whole flow — including every error
+ * branch the desktop's SendOTP component handles — is unit-testable. The
+ * network wrappers live in ./index.ts and only feed statuses in here.
+ */
+
+export type OtpPhase = "email" | "sending" | "code" | "verifying"
+
+export interface OtpState {
+    phase: OtpPhase
+    email: string
+    code: string
+    /** Blocking failure shown above the field. */
+    error: string | null
+    /** Transient confirmation ("New code sent"). */
+    notice: string | null
+    /** True during the 60s post-resend cooldown. */
+    resendBlocked: boolean
+}
+
+export const initialOtpState = (email = ""): OtpState => ({
+    phase: "email",
+    email,
+    code: "",
+    error: null,
+    notice: null,
+    resendBlocked: false,
+})
+
+export type OtpEvent =
+    | {type: "edit-email"; value: string}
+    | {type: "edit-code"; value: string}
+    | {type: "send"}
+    | {type: "sent"}
+    | {type: "resent"}
+    | {type: "resend-allowed"}
+    | {type: "verify"}
+    | {type: "failed"; message: string}
+    | {type: "restart"; message?: string}
+
+export function otpReducer(state: OtpState, event: OtpEvent): OtpState {
+    switch (event.type) {
+        case "edit-email":
+            return {...state, email: event.value, error: null}
+        case "edit-code":
+            return {...state, code: event.value, error: null}
+        case "send":
+            return {...state, phase: "sending", error: null, notice: null}
+        case "sent":
+            return {...state, phase: "code", code: "", error: null, notice: null}
+        case "resent":
+            return {...state, notice: "New code sent.", error: null, resendBlocked: true}
+        case "resend-allowed":
+            return {...state, resendBlocked: false}
+        case "verify":
+            return {...state, phase: "verifying", error: null, notice: null}
+        case "failed":
+            // Stay on whichever step the user was on; only the spinner ends.
+            return {
+                ...state,
+                phase: state.phase === "sending" ? "email" : "code",
+                error: event.message,
+                notice: null,
+            }
+        case "restart":
+            return {
+                ...initialOtpState(state.email),
+                error: event.message ?? null,
+            }
+        default:
+            return state
+    }
+}
+
+/** 60s, matching the desktop resend cooldown. */
+export const OTP_RESEND_COOLDOWN_MS = 60_000
+
+const GENERIC_ERROR = "Something went wrong. Try again."
+
+export type OtpOutcome =
+    | {kind: "ok"}
+    /** Recoverable: stay on the code step and let the user retype. */
+    | {kind: "retry"; message: string}
+    /** Unrecoverable: drop the attempt and go back to the email step. */
+    | {kind: "restart"; message: string}
+
+export function describeCreateCode(
+    result: {status: string; reason?: string} | null,
+): {kind: "ok"} | {kind: "failed"; message: string} {
+    if (result?.status === "OK") return {kind: "ok"}
+    if (result?.status === "SIGN_IN_UP_NOT_ALLOWED") {
+        return {kind: "failed", message: result.reason || "Sign-in is not allowed for this email."}
+    }
+    return {kind: "failed", message: GENERIC_ERROR}
+}
+
+export function describeResendCode(
+    result: {status: string} | null,
+): {kind: "ok"} | {kind: "restart"; message: string} {
+    if (result?.status === "OK") return {kind: "ok"}
+    if (result?.status === "RESTART_FLOW_ERROR") {
+        return {kind: "restart", message: "That code expired. Request a new one."}
+    }
+    return {kind: "restart", message: GENERIC_ERROR}
+}
+
+export function describeConsumeCode(
+    result: {
+        status: string
+        reason?: string
+        failedCodeInputAttemptCount?: number
+        maximumCodeInputAttempts?: number
+    } | null,
+): OtpOutcome {
+    switch (result?.status) {
+        case "OK":
+            return {kind: "ok"}
+        case "INCORRECT_USER_INPUT_CODE_ERROR": {
+            const left =
+                (result.maximumCodeInputAttempts ?? 0) - (result.failedCodeInputAttemptCount ?? 0)
+            return {
+                kind: "retry",
+                message:
+                    left > 0
+                        ? `Incorrect code. ${left} attempt${left === 1 ? "" : "s"} left.`
+                        : "Incorrect code.",
+            }
+        }
+        case "EXPIRED_USER_INPUT_CODE_ERROR":
+            return {kind: "retry", message: "That code expired. Request a new one."}
+        case "RESTART_FLOW_ERROR":
+            return {kind: "restart", message: "That sign-in attempt expired. Start again."}
+        case "SIGN_IN_UP_NOT_ALLOWED":
+            return {
+                kind: "restart",
+                message: result?.reason || "Sign-in is not allowed for this email.",
+            }
+        default:
+            return {kind: "restart", message: GENERIC_ERROR}
+    }
+}
diff --git a/web/mobile/src/pages/auth/callback/[[...provider]].tsx b/web/mobile/src/pages/auth/callback/[[...provider]].tsx
new file mode 100644
index 0000000000..5af45a5086
--- /dev/null
+++ b/web/mobile/src/pages/auth/callback/[[...provider]].tsx
@@ -0,0 +1,16 @@
+import Head from "next/head"
+
+import {OidcCallbackScreen} from "@/features/auth/OidcCallbackScreen"
+
+// Thin shell: /m/auth/callback/<providerId> — the device gate forwards the
+// provider's landing here when the mobile app started the flow.
+export default function AuthCallback() {
+    return (
+        <>
+            <Head>
+                <title>Signing in — Agenta</title>
+            </Head>
+            <OidcCallbackScreen />
+        </>
+    )
+}
diff --git a/web/mobile/src/pages/auth.tsx b/web/mobile/src/pages/auth/index.tsx
similarity index 65%
rename from web/mobile/src/pages/auth.tsx
rename to web/mobile/src/pages/auth/index.tsx
index d220e94f36..4d78842e91 100644
--- a/web/mobile/src/pages/auth.tsx
+++ b/web/mobile/src/pages/auth/index.tsx
@@ -2,8 +2,8 @@ import Head from "next/head"
 
 import {SignInScreen} from "@/features/auth/SignInScreen"
 
-// Thin shell: raw email/password sign-in (auth-lite). On success the root
-// context resolver takes over.
+// Thin shell: every sign-in method this deployment enables (password or
+// one-time code, plus OIDC). On success the root context resolver takes over.
 export default function Auth() {
     return (
         <>
diff --git a/web/mobile/tests/unit/authConfig.test.ts b/web/mobile/tests/unit/authConfig.test.ts
new file mode 100644
index 0000000000..ba6ab81d24
--- /dev/null
+++ b/web/mobile/tests/unit/authConfig.test.ts
@@ -0,0 +1,82 @@
+import {describe, expect, it} from "vitest"
+
+import {
+    getEmailSignInMode,
+    isOidcEnabled,
+    listOidcProviders,
+    OIDC_PROVIDER_META,
+    type EnvReader,
+} from "../../src/lib/auth/config"
+
+const env =
+    (values: Record<string, string>): EnvReader =>
+    (key) =>
+        values[key] ?? ""
+
+const GOOGLE = "NEXT_PUBLIC_AGENTA_AUTH_GOOGLE_OAUTH_CLIENT_ID"
+const GITHUB = "NEXT_PUBLIC_AGENTA_AUTH_GITHUB_OAUTH_CLIENT_ID"
+const AUTHN_EMAIL = "NEXT_PUBLIC_AGENTA_AUTHN_EMAIL"
+const OIDC_ENABLED = "NEXT_PUBLIC_AGENTA_AUTH_OIDC_ENABLED"
+
+describe("listOidcProviders", () => {
+    it("offers nothing when no client id is configured", () => {
+        expect(listOidcProviders(env({}))).toEqual([])
+    })
+
+    it("offers only the providers whose client id is set", () => {
+        expect(listOidcProviders(env({[GOOGLE]: "gid", [GITHUB]: "ghid"}))).toEqual([
+            {id: "google", label: "Google"},
+            {id: "github", label: "GitHub"},
+        ])
+    })
+
+    it("preserves the desktop provider order", () => {
+        const all = Object.fromEntries(OIDC_PROVIDER_META.map((p) => [p.envKey, "x"]))
+        expect(listOidcProviders(env(all)).map((p) => p.id)).toEqual(
+            OIDC_PROVIDER_META.map((p) => p.id),
+        )
+    })
+
+    it("covers all 13 client-id keys the desktop reads", () => {
+        expect(OIDC_PROVIDER_META).toHaveLength(13)
+    })
+})
+
+describe("isOidcEnabled", () => {
+    it("is on when the flag is true even with no client ids", () => {
+        expect(isOidcEnabled(env({[OIDC_ENABLED]: "true"}))).toBe(true)
+        expect(isOidcEnabled(env({[OIDC_ENABLED]: "TRUE"}))).toBe(true)
+    })
+    it("is on when any client id is set", () => {
+        expect(isOidcEnabled(env({[GOOGLE]: "gid"}))).toBe(true)
+    })
+    it("is off otherwise", () => {
+        expect(isOidcEnabled(env({[OIDC_ENABLED]: "false"}))).toBe(false)
+        expect(isOidcEnabled(env({}))).toBe(false)
+    })
+})
+
+describe("getEmailSignInMode", () => {
+    it("defaults to password when nothing is configured", () => {
+        expect(getEmailSignInMode(env({}))).toBe("password")
+    })
+
+    it("honors an explicit otp setting", () => {
+        expect(getEmailSignInMode(env({[AUTHN_EMAIL]: "otp"}))).toBe("otp")
+    })
+
+    it("honors an explicit password setting even when OIDC is on", () => {
+        expect(getEmailSignInMode(env({[AUTHN_EMAIL]: "password", [GOOGLE]: "gid"}))).toBe(
+            "password",
+        )
+    })
+
+    it("disables email on an SSO-only deployment (OIDC on, mode unset)", () => {
+        expect(getEmailSignInMode(env({[GOOGLE]: "gid"}))).toBe("disabled")
+        expect(getEmailSignInMode(env({[OIDC_ENABLED]: "true"}))).toBe("disabled")
+    })
+
+    it("disables email for an unrecognized mode", () => {
+        expect(getEmailSignInMode(env({[AUTHN_EMAIL]: "magic-link"}))).toBe("disabled")
+    })
+})
diff --git a/web/mobile/tests/unit/authDiscover.test.ts b/web/mobile/tests/unit/authDiscover.test.ts
new file mode 100644
index 0000000000..717c66f853
--- /dev/null
+++ b/web/mobile/tests/unit/authDiscover.test.ts
@@ -0,0 +1,39 @@
+import {describe, expect, it} from "vitest"
+
+import {formatSsoLabel, parseDiscoveredSso} from "../../src/lib/auth/discover"
+
+describe("formatSsoLabel", () => {
+    it("strips the sso: prefix from the third-party id", () => {
+        expect(formatSsoLabel("acme-inc", "sso:acme")).toBe("acme")
+    })
+    it("falls back to the slug for non-sso ids", () => {
+        expect(formatSsoLabel("acme-inc", "okta")).toBe("acme-inc")
+    })
+})
+
+describe("parseDiscoveredSso", () => {
+    const payload = (providers: unknown) => ({methods: {sso: {providers}}})
+
+    it("reads the providers the desktop reads", () => {
+        expect(
+            parseDiscoveredSso(payload([{id: "p1", slug: "acme-inc", third_party_id: "sso:acme"}])),
+        ).toEqual([{id: "p1", thirdPartyId: "sso:acme", label: "acme"}])
+    })
+
+    it("drops entries with no third_party_id (nothing to hand SuperTokens)", () => {
+        expect(parseDiscoveredSso(payload([{id: "p1", slug: "acme"}]))).toEqual([])
+    })
+
+    it("falls back to the third-party id when the slug is missing", () => {
+        expect(parseDiscoveredSso(payload([{id: "p1", third_party_id: "okta"}]))).toEqual([
+            {id: "p1", thirdPartyId: "okta", label: "okta"},
+        ])
+    })
+
+    it("returns nothing for a payload without sso providers", () => {
+        expect(parseDiscoveredSso({methods: {"email:password": true}})).toEqual([])
+        expect(parseDiscoveredSso(payload("not-an-array"))).toEqual([])
+        expect(parseDiscoveredSso({})).toEqual([])
+        expect(parseDiscoveredSso(null)).toEqual([])
+    })
+})
diff --git a/web/mobile/tests/unit/otpMachine.test.ts b/web/mobile/tests/unit/otpMachine.test.ts
new file mode 100644
index 0000000000..45454b9f9e
--- /dev/null
+++ b/web/mobile/tests/unit/otpMachine.test.ts
@@ -0,0 +1,154 @@
+import {describe, expect, it} from "vitest"
+
+import {
+    describeConsumeCode,
+    describeCreateCode,
+    describeResendCode,
+    initialOtpState,
+    otpReducer,
+    type OtpState,
+} from "../../src/lib/auth/otpMachine"
+
+const at = (overrides: Partial<OtpState> = {}): OtpState => ({
+    ...initialOtpState("a@b.co"),
+    ...overrides,
+})
+
+describe("otpReducer", () => {
+    it("starts on the email step", () => {
+        expect(initialOtpState().phase).toBe("email")
+    })
+
+    it("clears the error as soon as the user edits a field", () => {
+        const state = otpReducer(at({error: "Incorrect code."}), {type: "edit-code", value: "1"})
+        expect(state).toMatchObject({code: "1", error: null})
+    })
+
+    it("moves to the code step once the code is sent, wiping stale input", () => {
+        const sending = otpReducer(at({code: "999999"}), {type: "send"})
+        expect(sending.phase).toBe("sending")
+        expect(otpReducer(sending, {type: "sent"})).toMatchObject({phase: "code", code: ""})
+    })
+
+    it("returns to the email step when sending fails", () => {
+        const failed = otpReducer(at({phase: "sending"}), {type: "failed", message: "nope"})
+        expect(failed).toMatchObject({phase: "email", error: "nope"})
+    })
+
+    it("stays on the code step when verification fails, keeping the email", () => {
+        const failed = otpReducer(at({phase: "verifying"}), {type: "failed", message: "bad code"})
+        expect(failed).toMatchObject({phase: "code", error: "bad code", email: "a@b.co"})
+    })
+
+    it("blocks resend until the cooldown event, and shows a notice", () => {
+        const resent = otpReducer(at({phase: "code"}), {type: "resent"})
+        expect(resent).toMatchObject({resendBlocked: true, notice: "New code sent.", error: null})
+        expect(otpReducer(resent, {type: "resend-allowed"}).resendBlocked).toBe(false)
+    })
+
+    it("drops the notice when a new attempt starts", () => {
+        const resent = otpReducer(at({phase: "code"}), {type: "resent"})
+        expect(otpReducer(resent, {type: "verify"}).notice).toBeNull()
+    })
+
+    it("restart keeps the typed email but resets everything else", () => {
+        const restarted = otpReducer(at({phase: "code", code: "123456", resendBlocked: true}), {
+            type: "restart",
+            message: "expired",
+        })
+        expect(restarted).toEqual({
+            phase: "email",
+            email: "a@b.co",
+            code: "",
+            error: "expired",
+            notice: null,
+            resendBlocked: false,
+        })
+    })
+
+    it("restart without a message clears the error too", () => {
+        expect(otpReducer(at({error: "x"}), {type: "restart"}).error).toBeNull()
+    })
+})
+
+describe("describeCreateCode", () => {
+    it("accepts OK", () => {
+        expect(describeCreateCode({status: "OK"})).toEqual({kind: "ok"})
+    })
+    it("surfaces the backend reason when sign-in is not allowed", () => {
+        expect(describeCreateCode({status: "SIGN_IN_UP_NOT_ALLOWED", reason: "blocked"})).toEqual({
+            kind: "failed",
+            message: "blocked",
+        })
+    })
+    it("falls back to a generic message on a thrown/unknown result", () => {
+        expect(describeCreateCode(null).kind).toBe("failed")
+    })
+})
+
+describe("describeResendCode", () => {
+    it("accepts OK", () => {
+        expect(describeResendCode({status: "OK"})).toEqual({kind: "ok"})
+    })
+    it("restarts the flow on RESTART_FLOW_ERROR", () => {
+        expect(describeResendCode({status: "RESTART_FLOW_ERROR"}).kind).toBe("restart")
+    })
+    it("restarts on an unknown result", () => {
+        expect(describeResendCode(null).kind).toBe("restart")
+    })
+})
+
+describe("describeConsumeCode", () => {
+    it("accepts OK", () => {
+        expect(describeConsumeCode({status: "OK"})).toEqual({kind: "ok"})
+    })
+
+    it("reports the remaining attempts on a wrong code", () => {
+        expect(
+            describeConsumeCode({
+                status: "INCORRECT_USER_INPUT_CODE_ERROR",
+                failedCodeInputAttemptCount: 3,
+                maximumCodeInputAttempts: 5,
+            }),
+        ).toEqual({kind: "retry", message: "Incorrect code. 2 attempts left."})
+    })
+
+    it("singularizes the last attempt", () => {
+        expect(
+            describeConsumeCode({
+                status: "INCORRECT_USER_INPUT_CODE_ERROR",
+                failedCodeInputAttemptCount: 4,
+                maximumCodeInputAttempts: 5,
+            }),
+        ).toEqual({kind: "retry", message: "Incorrect code. 1 attempt left."})
+    })
+
+    it("omits the count when no attempts remain", () => {
+        expect(
+            describeConsumeCode({
+                status: "INCORRECT_USER_INPUT_CODE_ERROR",
+                failedCodeInputAttemptCount: 5,
+                maximumCodeInputAttempts: 5,
+            }),
+        ).toEqual({kind: "retry", message: "Incorrect code."})
+    })
+
+    it("keeps the user on the code step when the code expired", () => {
+        expect(describeConsumeCode({status: "EXPIRED_USER_INPUT_CODE_ERROR"}).kind).toBe("retry")
+    })
+
+    it("restarts on RESTART_FLOW_ERROR", () => {
+        expect(describeConsumeCode({status: "RESTART_FLOW_ERROR"}).kind).toBe("restart")
+    })
+
+    it("restarts with the backend reason when sign-in is not allowed", () => {
+        expect(describeConsumeCode({status: "SIGN_IN_UP_NOT_ALLOWED", reason: "linked"})).toEqual({
+            kind: "restart",
+            message: "linked",
+        })
+    })
+
+    it("restarts on a thrown/unknown result", () => {
+        expect(describeConsumeCode(null).kind).toBe("restart")
+    })
+})

From 7ccbf0ae12daa067f18cbc690dc7215cdfb2472e Mon Sep 17 00:00:00 2001
From: Arda Erzin <ardaerzin@gmail.com>
Date: Sat, 1 Aug 2026 02:56:56 +0300
Subject: [PATCH 04/19] docs(sessions): plan the single source of truth for
 desktop and mobile session logic

---
 .../agenta-sessions-consolidation/plan.md     | 530 ++++++++++++++++++
 1 file changed, 530 insertions(+)
 create mode 100644 docs/design/agenta-sessions-consolidation/plan.md

diff --git a/docs/design/agenta-sessions-consolidation/plan.md b/docs/design/agenta-sessions-consolidation/plan.md
new file mode 100644
index 0000000000..4616a8ffbe
--- /dev/null
+++ b/docs/design/agenta-sessions-consolidation/plan.md
@@ -0,0 +1,530 @@
+# Consolidating session logic into a single source of truth
+
+**Status:** PLAN — nothing implemented · **Date:** 2026-08-01 ·
+**Branch:** `feat/agenta-mobile-wave-1` (119 commits ahead of `release/v0.106.2`)
+
+**Question asked:** desktop and mobile now both implement session-list ordering, liveness
+polling, transcript revalidation and approval answering. Where does the shared logic live so
+there is exactly one implementation?
+
+**Answer in one line:** extend `@agenta/entities/session` (fetch/schema/cache/derivation) and
+`@agenta/chat` (conversation orchestration) — do **not** create `@agenta/sessions`. The reason
+is in §3.
+
+Everything below is grounded in files at the branch tip. Where I could not verify a claim from
+code I say so and state what would settle it.
+
+---
+
+## 1. Inventory
+
+### 1.1 `@agenta/entities/session` — the shared layer that already exists
+
+2,021 lines across 12 files (`web/packages/agenta-entities/src/session/`), UI-free (verified:
+zero hits for `antd|lexical|@/oss` in the tree). Public surface is
+`web/packages/agenta-entities/src/session/index.ts:1-108`.
+
+| Sub-layer | Files | What is there |
+| --- | --- | --- |
+| `api/` | `api.ts` (730), `client.ts` (106) | Every Fern-backed accessor: `querySessions`, `querySessionStreams`, `querySessionRecords`, `queryInteractions`, `respondInteraction`, `setSessionHeader`, `commandSessionStream`, `killSession`, `delete/archive/unarchiveSession`, mounts. |
+| `core/` | `schema.ts` (207), `liveness.ts` (90), `transcriptAdoption.ts` (47), `fileActivity.ts` (126), `mountBrowser.ts` (77), `pathUtils.ts` (22) | Pure derivations. `deriveStreamNest`/`deriveSessionLifecycle`/`refineLifecycleWithSandbox`; `shouldAdoptServerTranscript`. |
+| `state/` | `records.ts` (121), `mounts.ts` (247), `fileActivity.ts` (140) | Jotai + `atomWithQuery` caches. `sessionRecordsQueryKey` = `["session","records",projectId,sessionId]` (`state/records.ts:18-19`), 15 s stale, IndexedDB-persisted (`records.ts:23-36`), plus `revalidateSessionRecordsAtom` / `fetchSessionRecordsAtom`. |
+
+Coverage: 67 unit-test files in `web/packages/agenta-entities/tests/unit/`, nine of them
+session-specific (`session-transcript-adoption`, `session-liveness`, `session-query-schema`, …).
+
+**This is the current of convergence.** Upstream put `transcriptAdoption.ts` in `core/` this
+release and desktop consumes it (`web/oss/src/components/AgentChatSlice/hooks/useSessionHydration.ts:3,86-92`).
+Nothing in this plan should fight that.
+
+### 1.2 `@agenta/chat` — the headless conversation core, extracted but **not adopted**
+
+38 files under `web/packages/agenta-chat/src/`, six subpath exports
+(`web/packages/agenta-chat/package.json:19-27`), no antd/lexical/virtuoso (verified by grep).
+
+The load-bearing fact:
+
+```
+grep -rn "@agenta/chat" web/oss/src   →  0 hits
+grep -rn "@agenta/chat" web/ee/src    →  0 hits
+grep -rn "@agenta/chat" web/mobile/src → 6 hits
+```
+
+`web/oss/package.json:28` declares the dependency and never imports it. The package was
+**copy-extracted**, deliberately, and the OSS re-imports were deferred — this is written down
+in `docs/design/agenta-mobile/plans/2026-07-12-wp3a-chat-headless-core.md:7-19`:
+
+> "OSS re-import" steps were NOT executed (deferred to the desktop re-plumb) … The original
+> same-commit OSS re-imports … are DEFERRED to the desktop re-plumb PR, sequenced after the FE
+> PR queue drains and the shadcn branch lands — that PR deletes the OSS copies wholesale.
+
+So the consolidation this document is asked to plan is **already scoped in-repo**, with a
+sequencing precondition already stated. The new work is the *session* half (list, liveness,
+watch, approvals) that WP3a did not cover.
+
+Measured drift between the OSS original and the package copy (changed-line counts):
+
+| OSS file | package counterpart | drift |
+| --- | --- | --- |
+| `assets/trace.ts`, `assets/rewind.ts` | `agenta-chat/src/assets/*` | 3 lines each |
+| `hooks/useAgentChatQueue.ts` | `agenta-chat/src/hooks/useAgentChatQueue.ts` | 4 |
+| `hooks/useAgentModelKeyStatus.ts` | same path | 4 |
+| `state/expandState.ts` | `agenta-chat/src/state/expandState.ts` | 6 |
+| `assets/toolFormat.ts` | `agenta-chat/src/assets/toolFormat.ts` | 6 |
+| `assets/AgentChatTransport.ts` | `agenta-chat/src/transport/AgentChatTransport.ts` | 6 |
+| `state/sessionEphemera.ts` | `agenta-chat/src/state/sessionEphemera.ts` | 27 |
+| `assets/loadSession.ts` | `agenta-chat/src/assets/loadSession.ts` | 27 |
+| `assets/transcriptToMessages.ts` | `agenta-chat/src/assets/transcriptToMessages.ts` | 57 |
+| `hooks/useComposerAttachments.ts` | `agenta-chat/src/hooks/useComposerAttachments.ts` | 215 (genuinely diverged) |
+
+**The one that is actually dangerous — `agenta-chat/src/state/sessionMessages.ts`.** Its header
+(`:1-7`) says "keep byte-parity on the copied blocks if either side changes", and it has
+already broken parity in two behaviourally significant ways while writing **the same
+localStorage key**, `agenta:agent-chat:messages` (`sessionMessages.ts:22` vs
+`web/oss/src/components/AgentChatSlice/state/sessions.ts:140`):
+
+1. The package passes `undefined` for the storage impl (`sessionMessages.ts:24`) → default jotai
+   storage **with** the cross-tab `storage` subscribe. OSS deliberately strips `subscribe`
+   (`sessions.ts:102-106`) because an incoming cross-tab replacement unmounted a streaming
+   conversation and orphaned its `useChat` stream mid-turn.
+2. The package's `writeMessagesWithQuotaGuard` returns `void` (`sessionMessages.ts:44-46`), so it
+   has no `{evicted, persisted}` result and no counterpart to
+   `agenta:agent-chat:record-counts` (`sessions.ts:154-159`). OSS's watermark guard
+   (`sessions.ts:737-747`) is only correct while the two stores move together.
+
+Today this is latent (mobile is read-only and never writes messages). It becomes a live bug the
+moment either app writes messages through the package while the other reads OSS's watermark.
+
+### 1.3 `web/oss/src/components/AgentChatSlice` — the desktop app layer
+
+`state/` (11 files) and `hooks/` (18 files). Session-relevant:
+
+- **`state/sessions.ts` (881)** — the scope-keyed model: 5 `atomWithStorage` stores
+  (`agenta:agent-chat:{sessions,open-sessions,active-session,messages,record-counts}`,
+  `:109-159`), history ordering (`:185-213`), server reconciliation (`:429-505`), rename /
+  auto-title (`:581-623`, `setSessionHeader` at `:593,621`), archive/unarchive/delete
+  (`:333-405`), husk pruning (`:178-181,278-296`), quota guard (`:667-692`), watermark writes
+  (`:725-749`), `nowTick` (`:790-794`), `sessionLabel` (`:808-817`).
+- **`state/projectSessions.ts` (103)** — one low-priority `querySessions` per agent scope, key
+  `["session-list", projectId, appId]` (`:31`), stale 30 s / refetch 60 s (`:39-41`), dedup +
+  client sort (`:55-59`), `activity()` (`:66-70`), `toSummary()` (`:72-85`),
+  `useReconcileServerSessions` (`:93-103`). **No windowing is passed** — desktop fetches the
+  entire unwindowed list with `include_ended`/`include_archived` both defaulting `true`
+  (`web/packages/agenta-entities/src/session/api/api.ts:285-286,299-302`), every 60 s.
+- **`state/liveness.ts` (98)** — one project-scoped `querySessionStreams({isAlive:true})`, key
+  `["session-liveness","alive",projectId]` (`:33`), stale 10 s (`:40`),
+  `refetchInterval: data.length > 0 ? 15_000 : false` (`:42`), focus refetch (`:43`). Consumes
+  `deriveStreamNest`/`deriveSessionLifecycle` from the package — **no local re-implementation**.
+- **`hooks/useSessionHydration.ts` (280)** — the hybrid-SWR transcript: one
+  `adoptServerTranscript` (`:82-129`) shared by hydration / SWR / poll / relay, calling the
+  package guard (`:86-92`); watermark set **before** `setMessages` (`:103-109`); remote-run poll
+  `15_000 → 60_000` chained `setTimeout` with growth-reset backoff (`:20,27,218-249`); relay
+  wiring at `:257-277`, `enabled` scoped to the active session because antd Tabs keeps inactive
+  panes mounted (`:255-256`).
+- **`hooks/useSessionRecordsWatch.ts` (127)** — SSE relay. **Zero `@agenta/*` imports.** Header
+  at `:37-38` states it mirrors `web/mobile/src/features/chat/useSessionWatch.ts`.
+- **`hooks/useAgentChatSession.ts` (431)** — transport + `useChat` + every conversation side
+  effect, including the approval resume path (`:112-123,140,152-159,417`) and stop/kill
+  (`:365-388`).
+- `state/{sessionEphemera,expandState,scope,turnCaptures,fileLinks,panelLayout,rightPanel,virtualization,firstRunSeed}.ts` —
+  the first two are the ones duplicated into `@agenta/chat`; the rest are desktop-only.
+
+### 1.4 `web/mobile/src/features/{sessions,chat}` — the mobile app layer
+
+24 files. Deps allow `@agenta/{chat,entities,shared,sdk}` and nothing else
+(`web/mobile/package.json:23-26`) — no antd, no Lexical, no `@/oss`.
+
+- `sessions/useSessionsInfinite.ts` (33) — `useInfiniteQuery`, page 30, cursor
+  `{next: last.id, newest: last.updated_at ?? last.created_at}` (`:26-31`),
+  `includeArchived:false` (`:21-23`), stale 30 s, **no client sort**.
+- `sessions/useLivenessPoll.ts` (37) — hand-rewritten twin of desktop `state/liveness.ts` in
+  react-query form; identical constants (stale 10 s `:19`, `15_000|false` `:20`, focus `:21`);
+  local `livenessBySession` (`:28-37`) reading `stream.flags?.is_running` directly instead of
+  the package's `deriveSessionLifecycle`. Header at `:9-11` says "mirrors the desktop pattern".
+- `sessions/useActionableInteractions.ts` (48) — project-wide
+  `queryInteractions({actionableOnly:true})`, `pendingCountBySession` (`:39-48`); refetch
+  interval reads the **liveness cache entry cross-query** (`:27-33`).
+- `chat/useSessionTranscript.ts` (88) — imports `loadSessionMessages` from `@agenta/chat/assets`
+  and `revalidateSessionRecordsAtom` from `@agenta/entities/session` (`:3-4`), then hand-rolls
+  the entire adoption guard: session-switch ref (`:24-25`), `refreshed` race guard (`:34,43-45`),
+  `inFlight`/`pending` trailing queue (`:26-30,56-59,71-75`), never-adopt-empty (`:65`),
+  foreground-only (`:55`). **Does not use `shouldAdoptServerTranscript`** (verified: zero hits
+  under `web/mobile`).
+- `chat/useSessionWatch.ts` (133) + `chat/watchRelay.ts` (31) — the same SSE endpoint and the
+  same retry/throttle constants as desktop's `useSessionRecordsWatch`, plus badge-query
+  invalidation (`useSessionWatch.ts:64-69`) and the `watchAwarePollMs` fold (`watchRelay.ts:9-15`).
+- `chat/useApprovalActions.ts` (140) + `approvalTargets.ts` (20) + `steer.ts` (33) — the
+  detached `/respond` answering path.
+- `ChatHeader.tsx:16-21` — session title comes from its own
+  `useQuery(["mobile","session-stream",…])` calling `querySessionStreams({sessionId})[0]`.
+- Read-only: no rename, no archive, no kill anywhere in `web/mobile`
+  (`killSession|archiveSession|setSessionHeader|deleteSession` → 0 hits). The only mutations are
+  `commandSessionStream` (`StopButton.tsx:3,16`) and `respondInteraction`.
+
+**Copy-headers:** exactly one file in the whole mobile app carries a copy-provenance header
+(`web/mobile/src/middleware.ts:9-16`, a `@agenta/shared/utils/mobileGate` subset with an explicit
+"delete the twins when WP2 lands"). Everything else is a *silent* re-implementation with
+"mirrors the desktop" prose. That is the more dangerous kind: no marker for a future editor.
+
+---
+
+## 2. Duplication table
+
+`agree?` = do the two implementations produce the same result today.
+
+| # | Concept | Desktop | Mobile | Shared today | Agree? |
+| --- | --- | --- | --- | --- | --- |
+| 1 | Session-list fetch | `projectSessions.ts:26-44` — unwindowed, whole list, 60 s poll, `references:[{id:appId}]` | `useSessionsInfinite.ts:10-33` — windowed 30, cursor-paged, no poll | `querySessions` (`api.ts:280-340`) | **No.** Different windowing, different archive filter (`includeArchived` default `true` vs explicit `false`), different `references` scoping. |
+| 2 | Last-activity key | `activity()` `projectSessions.ts:66-70` = `Date.parse(updated_at ?? created_at)`; `sessionActivity()` `sessions.ts:185` = `lastMessageAt ?? createdAt ?? 0` | `useSessionsInfinite.ts:29` `last.updated_at ?? last.created_at`; `SessionRow.tsx:35` same | none | Yes semantically, **3 copies** of the same expression. |
+| 3 | List ordering | client sort `projectSessions.ts:59` **over the merged local+server model** `sessions.ts:189-194` | none — trusts the server | server `coalesce(updated_at, created_at) DESC, id DESC` (`api/oss/src/dbs/postgres/sessions/streams/dao.py:158-178`) | Yes on the server rows. Desktop's sort is **not** redundant — see §5.1. |
+| 4 | localStorage fold + reconciliation | `reconcileServerSessionsAtomFamily` `sessions.ts:429-505` (5 stores, husk model, `Math.max` activity merge `:447-448`) | **none** — pure server pages | none | N/A — mobile has no offline model. |
+| 5 | Liveness poll | `state/liveness.ts:29-45`, jotai `atomWithQuery` | `useLivenessPoll.ts:12-23`, react-query | `deriveStreamNest`/`deriveSessionLifecycle` (`core/liveness.ts`) | Constants identical; **desktop derives a lifecycle, mobile reads `flags.is_running` raw** (`useLivenessPoll.ts:34`). Diverges for the parked/zombie cases the lifecycle refinement exists to handle. |
+| 6 | Transcript replay | `loadSessionMessages` (`oss/.../assets/loadSession.ts`) | `loadSessionMessages` (`@agenta/chat/assets`) | package copy exists, OSS doesn't import it | 27 lines of drift. |
+| 7 | Adoption guard | `shouldAdoptServerTranscript` via `useSessionHydration.ts:86-92` | hand-rolled in `useSessionTranscript.ts:24-30,43-45,65` | `core/transcriptAdoption.ts:28-47` | **No.** Mobile's guard has no record-watermark rule at all. |
+| 8 | Records revalidation | `revalidateSessionRecordsAtom` (`useAgentChatSession.ts:165-169`, `useSessionHydration.ts:261-271`) | `revalidateSessionRecordsAtom` (`useSessionTranscript.ts:61-62`) | `state/records.ts` | **Yes** — the one clean case. |
+| 9 | Watch relay (SSE) | `useSessionRecordsWatch.ts` (127) | `useSessionWatch.ts` (133) + `watchRelay.ts` (31) | none | Same endpoint, same 3 s throttle, same 1 s→30 s jittered backoff, same visibility rule, same auth-refresh-then-reopen. Mobile adds badge invalidation + poll folding. **Two files, one contract.** |
+| 10 | Approval answering | re-invoke: `addToolApprovalResponse` → `sendAutomaticallyWhen`/`agentShouldResumeAfterApproval` → `AgentChatTransport` → `POST {serviceUrl}/invoke` (`useAgentChatSession.ts:112-123,152-159`; `AgentConversation.tsx:323-339`) | `respondInteraction` → `POST /sessions/interactions/{id}/respond` (`useApprovalActions.ts:97-101`) | `respondInteraction` exists in the package and desktop uses it only in `SessionInspector/api.ts:132` | **No — genuinely different, and both are correct for their caller.** §5.2. |
+| 11 | Pending-approval detection | 3 detectors: `getPendingApprovals` (`components/ApprovalDock.tsx:35-47`), `getPendingConnectInteraction` (`components/InteractionDock.tsx:41-53`), `isHitlPending` (`@agenta/playground`, via `useAgentChatQueue.ts:76`) | 2 detectors: `getPendingApprovals` (`@agenta/chat/model/approvals.ts:29-41`) for the dock, `pendingCountBySession` (`useActionableInteractions.ts:39-48`) for the badge | `@agenta/chat/model/approvals.ts` | **No.** Transcript-derived (last assistant message only) vs interactions-table-derived (all actionable rows, no `kind` filter). They disagree for elicitation rows: list badges, dock can't answer. |
+| 12 | Session title | `sessionLabel` (`sessions.ts:808-817`) title → first user text → `Chat N`; rename/auto-title write `setSessionHeader` (`:593,621`) | `session.name ?? "Untitled session"` (`SessionRow.tsx:41`); chat header re-queries the row (`ChatHeader.tsx:16-21,31`) | `setSessionHeader` (`api.ts:~380`) | **No.** Mobile has no fallback chain and no rename. |
+| 13 | Archive / delete / kill | `sessions.ts:333-405` + `killSession` (`SessionHistoryMenu.tsx:69`, `useAgentChatSession.ts:371`) | absent | remotes all in the package | N/A — mobile parity gap, not a duplication. |
+| 14 | Stop (cooperative cancel) | `commandSessionStream` (`useAgentChatSession.ts:387`) | `commandSessionStream` (`StopButton.tsx:16`) | `api.ts:398-421` | **Yes.** |
+| 15 | Query-key namespaces | `["session-list",…]`, `["session-liveness",…]` (jotai) | `["mobile","sessions"…]`, `["mobile","session-liveness"…]`, `["mobile","actionable-interactions"…]`, `["mobile","session-stream"…]` | `sessionRecordsQueryKey`/`sessionMountsQueryKey` only | **No.** This is why `useSessionWatch.ts:64-68` must invalidate react-query keys *and* set a jotai atom. |
+| 16 | Message persistence + watermark | `sessions.ts:139-159,667-692,725-749` | none (read-only) | `@agenta/chat/state/sessionMessages.ts` — same localStorage key, drifted | **No** — see §1.2. Latent, becomes live on adoption. |
+
+Net: **rows 2, 5, 6, 7, 9, 11, 15 are true duplication.** Rows 1, 3, 10, 12 are *divergence*
+(deliberate or accidental — resolved in §5). Rows 4, 13 are asymmetry, not duplication. Row 8
+is the model to copy. Row 16 is a latent defect the consolidation must fix on the way through.
+
+---
+
+## 3. Structural recommendation
+
+### Verdict: **no new package.** Extend `@agenta/entities/session`, and put conversation-level orchestration in `@agenta/chat`.
+
+A new `@agenta/sessions` would have to sit between `entities` and `chat` in the hierarchy
+`shared ← ui ← entities ← entity-ui ← playground ← playground-ui`
+(`web/AGENTS.md:444-445`; `@agenta/chat` depends on `entities`, `playground`, `shared` —
+`web/packages/agenta-chat/package.json:29-33`). Everything it would contain either:
+
+- depends on `session/core/schema.ts` types and `session/api/*` accessors → it would import
+  `@agenta/entities`, so it must sit **above** entities; or
+- is consumed by `@agenta/chat` → it must sit **below** chat.
+
+That is exactly the slot `@agenta/entities/session` already occupies. Creating a package to
+hold code that imports entities and is imported by chat buys one thing (a name) and costs four:
+a fifth workspace package to build/lint/typecheck, a new `transpilePackages` entry in two
+next.configs, a split of nine already-passing session test files across two suites, and a fresh
+boundary argument on every future file ("entities/session or sessions?"). The upstream signal
+is unambiguous: `transcriptAdoption.ts` was placed in `entities/session/core` this release, and
+desktop imports it from there.
+
+**Where the real split already is, and should stay:**
+
+| Layer | Package | Owns | Test suite |
+| --- | --- | --- | --- |
+| Data | `@agenta/entities/session` | Fern accessors, zod schemas, pure derivations, shared query caches + revalidate atoms, query-key factories | `agenta-entities` unit (~934) |
+| Conversation | `@agenta/chat` | Transcript model, view-models, transport, headless hooks, skin registry — everything that needs `ai`/`@ai-sdk/react` as a peer | `agenta-chat` (207) |
+| App | `web/oss`, `web/mobile` | Rendering, layout, virtualization, scroll, routing, per-app query-client wiring | oss tsc gate; mobile (83) |
+
+The rule that keeps them apart: **`@agenta/entities/session` never imports `ai`.**
+`@agenta/chat` already declares `ai` and `@ai-sdk/react` as peers
+(`agenta-chat/package.json:34-39`). Anything that touches `UIMessage` is chat, not entities.
+That is a mechanical test a reviewer can apply without judgement.
+
+### The one new subpath: `@agenta/entities/session` gains a `state/list.ts` and a `hooks/` seam
+
+Two things in the inventory have no home under the current split:
+
+- the **list model** (fetch + windowing + activity key + ordering) — pure data, belongs in
+  entities `state/`;
+- the **SSE watch relay** — a React hook with a DOM `EventSource` and no `ai` dependency. It
+  belongs in entities too, but entities currently has no React-hook precedent in `session/`.
+  `session/state/*` is jotai atoms, not hooks. I'd add `session/hooks/useSessionWatch.ts` and a
+  `"./session/hooks"` export rather than force a hook into `state/`.
+
+`@agenta/entities` is not React-free (it ships jotai atoms and molecules), so a hook is not a
+boundary violation — but it is a new shape for this domain and worth calling out in review.
+
+### The boundary — what does NOT go into the shared layer
+
+A package without a stated exclusion list becomes a dumping ground. Excluded, permanently:
+
+1. **Anything that renders.** No antd, no shadcn, no Lexical, no `react-virtuoso`. Mobile cannot
+   import antd; desktop will not import shadcn until the migration lands.
+2. **Virtualization and scroll engineering.** `useVirtuosoTranscript.tsx`, `useTranscriptScroll.ts`,
+   `useScrollIntent.ts`, `state/virtualization.ts`, `virtuosoState.ts` (desktop);
+   `useTranscriptAutoScroll.ts`, `useSessionListScrollRestore.ts` (mobile). These encode
+   completely different scrollers with different correctness conditions.
+3. **Panel/layout/tab state.** `state/panelLayout.ts`, `state/rightPanel.ts`, and the whole
+   open-tabs model in `sessions.ts:123-135,206-213` — antd `Tabs` semantics (inactive panes stay
+   mounted, `useSessionHydration.ts:255-256`) are a desktop fact. Mobile is one session per route.
+4. **The scope-key concept.** `state/scope.tsx` + `defaultScopeKeyAtom` (`sessions.ts:76-84`,
+   which reads `window.location.pathname` with an `/apps/:id` regex) is a desktop routing
+   artifact. Mobile scopes by `projectId` from the route.
+5. **The localStorage session cache** (`agenta:agent-chat:*`). Mobile has no offline session
+   model and does not want one. The *reconciler shape* can be shared as a pure function; the
+   five `atomWithStorage` stores stay in `web/oss`.
+6. **App-specific query-client policy.** Mobile sets `refetchOnWindowFocus:false` globally
+   (`web/mobile/src/lib/queryClient.ts:7-8`) and each hook opts back in; desktop uses jotai
+   `atomWithQuery` against a different client. Shared code exposes **query options factories**,
+   never mounted queries — the caller decides jotai vs react-query, priority, and focus policy.
+7. **Auth.** Desktop uses `supertokens-auth-react` (`useSessionRecordsWatch.ts:3`), mobile
+   `supertokens-web-js` via `@/lib/auth`. A shared watch hook takes an
+   `onAuthRetry?: () => Promise<unknown>` option; it never imports supertokens.
+8. **Onboarding/first-run, drawer scopes, turn inspector, file links** — desktop product
+   surfaces with no mobile counterpart.
+
+Positive form of the same rule, borrowed from `@agenta/chat`'s proven shape: **the shared layer
+never branches on "desktop" or "mobile".** If a function needs to know which app called it, the
+difference is an option the caller passes, or the code is in the wrong layer.
+
+---
+
+## 4. Migration plan
+
+Ordered so desktop never breaks and each step is independently reviewable. "Touches `web/oss`?"
+is the column that matters for conflict risk — see §6.
+
+Standing gates for every step:
+
+```bash
+cd web/packages/agenta-entities && pnpm run check && pnpm run test:unit   # ~934
+cd web/packages/agenta-chat     && pnpm run check && pnpm run test:unit   # 207
+cd web/packages/agenta-shared   && pnpm run test:unit                     # 330
+cd web/mobile                   && pnpm run types:check && pnpm test      # 83
+cd web && pnpm --filter @agenta/oss exec tsc                              # signature diff, not count
+cd api && py-run-tests                                                    # sessions 238
+```
+
+The oss gate is a **signature diff**, never an error count — the count fluctuates with cache
+state (`feedback_tsc_count_gate_masks_new_errors`). Gate on "no error mentions a symbol this
+step touched".
+
+| # | Step | Moves | Call sites become | Proof | Touches `web/oss`? | Rollback |
+| --- | --- | --- | --- | --- | --- | --- |
+| **S0** | Fix the drifted twin **before** anything else | Re-align `@agenta/chat/state/sessionMessages.ts` to `sessions.ts` byte-parity: pass `tabLocalStorage()` (port the `subscribe`-stripping storage), and either add the record-count watermark store or make the writer refuse to write the shared key without one | nothing changes (no consumer) | new `agenta-chat` unit test: writing through the package leaves `agenta:agent-chat:record-counts` consistent with the OSS reader's expectation | **No** | revert one file |
+| **S1** | Activity key + ordering, one definition | New `session/core/ordering.ts`: `sessionActivityMs(stream)` (= `Date.parse(updated_at ?? created_at)`, NaN→0), `compareByActivityDesc`, `dedupeBySessionId` | `projectSessions.ts:55-70` imports them; `useSessionsInfinite.ts:29` and `SessionRow.tsx:35` import `sessionActivityMs` | entities unit tests over the three current behaviours (NaN, missing `updated_at`, dedupe tie) | yes, ~15 lines in one file | revert; the local copies are 5 lines each |
+| **S2** | Shared list query **options** | `session/state/list.ts`: `sessionListQueryKey(projectId, {references, search, windowing})` + `sessionListQueryOptions(...)` returning `{queryKey, queryFn, staleTime}` — **not** a mounted query | `projectSessionsQueryAtomFamily` wraps it in `atomWithQuery`; `useSessionsInfinite` wraps it in `useInfiniteQuery` | key-shape unit test; mobile 83 unchanged; oss tsc | yes, `projectSessions.ts` only | revert; both call sites keep working with inline options |
+| **S3** | Liveness derivation parity | nothing moves — mobile switches `useLivenessPoll.ts:28-37` from raw `flags.is_running` to `deriveStreamNest`/`deriveSessionLifecycle` | mobile badge map derived, not read | mobile `livenessBadge.test.ts` extended with a parked/zombie fixture; entities `session-liveness` already covers the derivation | **No** | revert one file |
+| **S4** | Shared watch relay | New `session/hooks/useSessionWatch.ts` + `session/core/watchRelay.ts` (URL builder, `MIN_INTERVAL_MS`, jittered backoff, `watchAwarePollMs`). Options: `{sessionId, projectId, enabled, apiUrl, onRecordsChanged, onLifecycle?, onInteraction?, onAuthRetry?}` | `useSessionRecordsWatch.ts` → thin desktop wrapper passing `Session.attemptRefreshingSession`; `useSessionWatch.ts` → thin mobile wrapper passing `tryRefreshSession` + the two badge invalidations | port `web/mobile/tests/unit/watchRelay.test.ts` into `agenta-entities/tests/unit`; both apps' wrappers typecheck | yes, one hook replaced by a wrapper | revert; both hooks are self-contained |
+| **S5** | Adoption guard parity | nothing moves — mobile's `useSessionTranscript.ts` adopts `shouldAdoptServerTranscript`; the trailing-refresh queue (`:26-30,56-59`) stays mobile-local for now | mobile gains the record-watermark rule | new mobile unit test for the guard call; entities `session-transcript-adoption` already covers the rule table | **No** | revert one file |
+| **S6** | Transcript replay, one copy | Delete `web/oss/.../assets/loadSession.ts` + `transcriptToMessages.ts`; OSS imports `@agenta/chat/assets` | `useSessionHydration.ts:9` and callers re-point | **This is the WP3a "desktop re-plumb" step.** Diff the 27+57 drifted lines first and decide each one; `agenta-chat` fixture tests (207) are the regression net; live smoke on a session with tools + an approval + attachments | **yes, materially** | revert the import swap; the OSS files come back from git |
+| **S7** | Pending-approval, one definition | `session/core/pendingApprovals.ts`: `actionableRowsToPending(rows)` alongside chat's transcript-derived `getPendingApprovals`, plus a documented reconciliation rule (which wins when they disagree) | desktop's three detectors and mobile's two collapse to two named functions with one stated precedence | unit tests for the disagreement cases (elicitation row present, transcript tail stale) | yes | revert |
+| **S8** | Answer-an-interaction, one entry point | `@agenta/chat` gains `useInteractionAnswer({strategy})` wrapping target selection (`approvalTargets.ts`), the stale re-read, 409 handling, and the settle state machine; strategy `"detached-respond"` \| `"resume-invoke"` injected by the caller | mobile passes `detached-respond`; desktop passes `resume-invoke` and keeps its transport | mobile 83 + the new hook's tests; desktop live smoke on approve / deny / approve-all | yes | revert; mobile's `useApprovalActions` is intact underneath |
+| **S9** | Session title + list-row model | `session/core/sessionLabel.ts` (title → first user text → `Chat N`); mobile gains rename via `setSessionHeader` if wanted | both apps share the fallback chain | entities unit test | yes | revert |
+| **S10** | Optional, only if desired | Lift the reconciler as a **pure** function `reconcileSessions(local, remote)` into `session/core/reconcile.ts`; the jotai stores stay in `web/oss` | `sessions.ts:429-505` becomes store-plumbing around a pure call | the merge rules (`:443-455`) get a real unit test they don't have today | yes, the biggest single oss diff | revert |
+
+**Steps that need no `web/oss` change at all: S0, S3, S5.** Land those first — they are pure
+mobile/package work and cannot conflict with the FE PR queue.
+
+**Steps S1–S2, S4, S7–S9 are small, surgical oss diffs** (one file each, mostly import swaps).
+**S6 and S10 are the real re-plumb** and should be their own PR, sequenced last.
+
+---
+
+## 5. The three called-out decisions
+
+### 5.1 Ordering — server-side wins for the fetch; the client sort stays, but for a different reason
+
+The server already orders **both** paths. Windowed:
+`api/oss/src/dbs/postgres/sessions/streams/dao.py:156-166` (`apply_windowing(attribute="updated_at",
+order="descending")`); unwindowed — the branch desktop hits, since `projectSessions.ts` passes no
+`limit`/`next`/`newest` and `querySessions` only attaches `windowing` when a caller opts in
+(`api.ts:299-302`) — `dao.py:174-178`:
+
+```python
+stmt = stmt.order_by(
+    func.coalesce(SessionStreamDBE.updated_at, SessionStreamDBE.created_at).desc(),
+    SessionStreamDBE.id.desc(),
+)
+```
+
+Desktop's own comment says as much (`projectSessions.ts:63-65`: "belt-and-suspenders"). But the
+sort at `projectSessions.ts:59` is **not** the sort that orders the desktop sidebar. The sidebar
+reads `sessionHistoryAtomFamily` (`sessions.ts:189-194`), which sorts the **merged** model —
+local-optimistic rows included. `bumpSessionActivityAtomFamily` stamps `Date.now()` on the
+`streaming → settled` transition (`sessions.ts:634-644`) and the reconciler keeps
+`Math.max(local, remote)` (`sessions.ts:447-448`). That is what makes a just-finished turn jump
+to the top inside the 60 s poll window, before the server row's `updated_at` is refetched.
+
+**Recommendation:**
+
+- The **server ordering is canonical** and both clients must consume the server order as-is. Do
+  not sort server pages client-side — for mobile that would be actively wrong, since sorting a
+  cursor-paged list breaks the cursor invariant.
+- Delete the sort at `projectSessions.ts:59`; keep the dedup (a real need — two rows can share a
+  `session_id`), which needs `activity()` regardless.
+- Keep `sessions.ts:189-194`. Rename it in review to say what it is: **merge ordering over the
+  optimistic local layer**, not list ordering. It is not a second implementation of the server's
+  order; it is the price of having an offline cache. If desktop ever drops the localStorage
+  cache, this sort goes with it.
+- Move the one shared expression (`updated_at ?? created_at → epoch ms`) into
+  `session/core/ordering.ts` (S1). Three copies today: `projectSessions.ts:66-70`,
+  `useSessionsInfinite.ts:29`, `SessionRow.tsx:35` — plus `sessions.ts:185` on the *local* model,
+  which stays separate because its input type is different.
+- **Also fix the windowing asymmetry (not strictly ordering, but the same call).** Desktop
+  fetches the entire unwindowed session list with `include_ended` and `include_archived` both
+  `true`, every 60 s. For a workspace with thousands of sessions that is the scaling cliff of
+  this whole feature. Mobile already paginates. I did not measure the payload — **what would
+  settle it: a `querySessions` response size and duration on a large EE project.**
+
+### 5.2 Approval answering — the premise "only one binds warm" is not what the evidence says
+
+Both paths bind warm. The evidence:
+
+- **Desktop re-invoke** — `POST {serviceUrl}/invoke` with the full history carrying the
+  `{approved, interactionToken}` envelope; runner finds the parked match and calls
+  `respondPermission("once"|"reject")` on the **same warm sandbox**
+  (`docs/design/agenta-mobile/plans/2026-07-27-mobile-approvals-steering.md:70-83`).
+- **Detached `/respond`** — CAS `pending → responded`, then a taskiq worker rebuilds the request
+  and fires a detached invoke (`…steering.md:93-100`). The dispatcher was **deliberately given
+  fingerprint parity so mobile answers warm-resume** (`…steering.md:452-456`), and the live
+  measurement table (`…steering.md:457-465`) labels the respond-dispatcher arm `warm`.
+
+What actually differs — and it is sharper than warm/cold:
+
+| | desktop re-invoke | detached `/respond` |
+| --- | --- | --- |
+| What the client must hold | invocation URL + full `UIMessage[]` history + hydrated `workflowMolecule` (`buildAgentRequest`, `@agenta/playground`) | interaction `id` + `projectId` only |
+| Exactly-once | **none at answer time.** The row is transitioned by the *runner* after resume (`…steering.md:83`). Two clients answering concurrently both fire an invoke | CAS at the endpoint; second answer is a `409`, surfaced as `isInteractionConflict` (`api.ts:172-174`) |
+| Who holds the token stream | the answering client — live tokens render immediately | nobody; the answerer learns the outcome from records/watch |
+| Config on resume | client sends `data.parameters` inline, draft-aware (`agentRequest.ts:353-372`) — correct even for a dirty draft | server replays the gate's stamped `data.parameters` (`…2026-07-29-effective-turn-config.md:1-20`) — correct as of this branch, degrades to reference-hydration for pre-stamp rows |
+| Failure mode if misused | a client that cannot reproduce the exact history gets `approval-mismatch (history) → evict + cold`, and the row **stays pending** (`web/mobile/src/features/chat/useApprovalActions.ts:40-42`; mirrored `api.ts:181-184`) | none of that class |
+| Steer / deny-with-note | delivered (desktop sends the note as its own turn, `AgentConversation.tsx:337`) | **dropped on the warm path** — `run-turn.ts` `if (opts.resume)` never calls `session.prompt`; measured (`…steering.md:462`), tracked as #5444 |
+
+**Recommendation: `/respond` is the default and the only *durable* answer path; the re-invoke
+is a live-attached fast path, and both go through one entry point (S8).**
+
+Concretely: `useInteractionAnswer({strategy})` in `@agenta/chat` owns everything that is the
+same — target selection (`approvalTargets.ts`, including the `token` vs `id` trap documented at
+`approvalTargets.ts:6-12`), the pre-answer staleness re-read, 409 tolerance, the
+`idle → resuming → idle` settle with the 60 s re-arm. The strategy is the injected difference.
+Desktop keeps `resume-invoke` **only while it is the current stream holder** (live gate present,
+status streaming/awaiting); a reload-restored cold tail should use `detached-respond` like
+mobile, because that is exactly the case where desktop cannot guarantee history fidelity either.
+
+Two things I could not verify and that should be tested before S8 lands:
+
+- **Does a desktop re-invoke race a mobile `/respond` on the same gate?** The desktop path has no
+  client-side CAS. *Settles it:* answer one gate from both clients within a second and inspect
+  the interactions row + runner log for a double dispatch.
+- **Does `/respond` produce a live stream a desktop tab could attach to?** If not, moving desktop
+  wholesale to `/respond` would regress perceived latency on approve. *Settles it:* answer via
+  `/respond` from a desktop tab with the chat open and time first-token-repaint vs the re-invoke
+  path.
+
+### 5.3 The two watch relays — one shared hook, options for the rest
+
+`web/oss/.../useSessionRecordsWatch.ts` (127) and `web/mobile/.../useSessionWatch.ts` (133) +
+`watchRelay.ts` (31) are the same protocol implementation twice: same endpoint
+(`/sessions/streams/watch?session_id=…&project_id=…`), same `withCredentials`, same 3 s
+connect-revalidation throttle, same 1 s→30 s jittered backoff, same
+`visibilitychange`-close/reopen, same "only a fatal `CLOSED` retries; refresh auth first, since
+the usual cause is a 401 at the token boundary". Desktop's own header says so
+(`useSessionRecordsWatch.ts:37-38`).
+
+Differences that become **options**, not forks:
+
+| Difference | Option |
+| --- | --- |
+| desktop `supertokens-auth-react` vs mobile `supertokens-web-js` | `onAuthRetry?: () => Promise<unknown>` |
+| desktop `getAgentaApiUrl()` vs mobile `getApiUrl()` | `apiUrl: string` |
+| mobile invalidates `livenessQueryKey`/`actionableInteractionsQueryKey`; desktop invalidates nothing | `onLifecycle?`, `onInteraction?` callbacks |
+| mobile folds cadence via `watchAwarePollMs`; desktop's poll is in `useSessionHydration` | export `watchAwarePollMs` as a pure helper; neither app's polling moves |
+| desktop's `enabled` is scoped to the *active* tab (antd Tabs keeps panes mounted) | already an `enabled` prop |
+
+`web/mobile/tests/unit/watchRelay.test.ts` becomes the package's test — the pure helpers are
+already extracted on the mobile side, which makes this the cheapest high-value step in the plan.
+
+---
+
+## 6. Risk and sequencing
+
+### Context
+
+- This branch is 119 commits ahead of `release/v0.106.2` and has no PR yet.
+- The FE PR queue is deep (tsc-cleanup #5464, DrillIn dedup/migration, sessions #5486/#5500,
+  attachments/voice #5458/#5459, cancel-steer, batch-approvals #5470 — most of them touching
+  `web/oss/src/components/AgentChatSlice`).
+- A local antd→shadcn migration branch is in flight against the presentational set.
+- Work has twice been stopped for touching OSS agent chat.
+- WP3a already recorded the sequencing rule
+  (`docs/design/agenta-mobile/plans/2026-07-12-wp3a-chat-headless-core.md:15-17`): the re-plumb
+  lands "after the FE PR queue drains and the shadcn branch lands".
+
+### Recommended order
+
+**Wave 0 — now, alongside the current PR.** S0, S3, S5. Zero `web/oss` files. S0 in particular
+is a latent-defect fix that should not wait for anything: a package that writes
+`agenta:agent-chat:messages` without the watermark, with cross-tab `subscribe` re-enabled, is a
+loaded gun pointed at the desktop chat the moment S6 lands.
+
+**Wave 1 — after this branch's PR merges.** S1, S2, S4, S7. Each is one small oss diff (an
+import swap or a deleted local helper). Land them as four separate PRs, not one — they touch
+different files and a reviewer can approve each in minutes.
+
+**Wave 2 — after the FE queue drains AND the shadcn branch lands.** S6, S8, S9, S10. This is the
+WP3a desktop re-plumb, and it deletes OSS copies wholesale.
+
+### Conflict surface per step
+
+| Step | oss files touched | Conflict risk |
+| --- | --- | --- |
+| S0, S3, S5 | 0 | **none** |
+| S1 | `projectSessions.ts` (~15 lines) | low — small file, few open PRs touch it |
+| S2 | `projectSessions.ts` | low, but **serialize with S1** (same file) |
+| S4 | `hooks/useSessionRecordsWatch.ts` (whole file → wrapper) | low — the file is new on this branch (`git status` shows it added) and has few other editors |
+| S7 | `components/ApprovalDock.tsx`, `components/InteractionDock.tsx`, `hooks/useAgentChatQueue.ts` | **medium-high** — #5470 (batch approvals) and the friendly-approvals work both live here |
+| S8 | `AgentConversation.tsx`, `hooks/useAgentChatSession.ts` | **high** — `AgentConversation.tsx` is the most-contended file in the repo; cancel-steer, elicitation-resume and approval-batch branches all edit it |
+| S9 | `state/sessions.ts` | medium |
+| S6 | `assets/loadSession.ts`, `assets/transcriptToMessages.ts` + every importer | **high**, and it is a semantic merge (57 drifted lines) not a textual one |
+| S10 | `state/sessions.ts` (~75 lines) | medium-high |
+
+### What must wait for the antd→shadcn branch
+
+Strictly speaking, **nothing in this plan renders**, so none of S0–S10 has a hard shadcn
+dependency. But two have a soft one:
+
+- **S6** deletes OSS transcript-building code whose output feeds `AgentMessage.tsx`,
+  `ToolActivity.tsx`, `ApprovalDock.tsx` — the exact components the shadcn migration is
+  rewriting. Landing S6 first means the shadcn branch rebases onto a changed data source;
+  landing it second means one rebase of S6. Second is cheaper.
+- **S8** touches `ApprovalDock.tsx`'s call site. Same argument.
+
+S7's *pure* half (the `core/pendingApprovals.ts` function + tests) can land in Wave 1; only the
+call-site swap needs to wait.
+
+### Top 3 risks
+
+1. **S6/S8 land into a contended file and get reverted.** `AgentConversation.tsx` and the
+   `assets/` transcript pair are edited by at least four in-flight branches. *Mitigation:* Wave 2
+   only, one PR per step, and a pre-flight `git log --oneline <base>..<each-open-branch> --
+   web/oss/src/components/AgentChatSlice` to see who else is in the file that week.
+2. **The `sessionMessages.ts` twin silently corrupts a desktop transcript.** Same localStorage
+   key, no watermark, cross-tab subscribe re-enabled — the exact hazard `sessions.ts:102-106`
+   was written to prevent. Today it is dormant only because no app mounts both. *Mitigation:*
+   S0, in Wave 0, before anything else.
+3. **Consolidating approvals flattens a difference that is load-bearing.** The re-invoke and
+   `/respond` paths differ in exactly-once semantics, stream ownership, config source **and**
+   steer delivery (§5.2). A single "just use `/respond`" would regress live desktop latency and
+   silently drop deny-with-note on the warm path (measured, `…steering.md:462`). *Mitigation:*
+   S8 shares the *orchestration* and keeps the strategy injectable; run the two verification
+   tests in §5.2 before choosing a desktop default.
+
+Runner-up risk worth naming: session-id-keyed `atomFamily` instances are never `.remove()`d
+except `expandedValueAtomFamily` (`state/expandState.ts:65-66`). Every shared atom family this
+plan adds inherits that leak. Give each new family a documented eviction call site or don't add
+it.
+
+---
+
+## 7. Open questions
+
+| # | Question | What would settle it |
+| --- | --- | --- |
+| Q1 | Should desktop paginate the session list like mobile? | Measure `querySessions` payload size + duration on a large EE project. |
+| Q2 | Does a desktop re-invoke race a mobile `/respond` on the same gate? | Answer one gate from both clients within a second; inspect the interactions row and the runner dispatch log. |
+| Q3 | Can a desktop tab attach to the stream a `/respond` resume produces? | Answer via `/respond` with the desktop chat open; time first-token repaint against the re-invoke path. |
+| Q4 | Is a React hook acceptable inside `@agenta/entities/session` (S4)? | Reviewer call. `entities` already ships jotai atoms; a hook is new for this domain but not for the package. |
+| Q5 | When two pending-approval detectors disagree (elicitation row badges the list, dock can't answer it), which is authoritative? | Product decision, needed before S7 can state a precedence rule. |
+| Q6 | Which of the 57 drifted lines in `transcriptToMessages.ts` are fixes and which are regressions? | Line-by-line diff review during S6 — I did not read them. |

From 38f9605cf243ab5f99fc68e4679147b5beccc0d6 Mon Sep 17 00:00:00 2001
From: Arda Erzin <ardaerzin@gmail.com>
Date: Sat, 1 Aug 2026 09:02:51 +0300
Subject: [PATCH 05/19] fix(chat): restore the message store's OSS semantics on
 the shared localStorage key

The package copy of the agent-chat message store writes the same localStorage key
as the desktop original but had drifted twice: it used jotai's default storage,
re-enabling the cross-tab `storage` subscribe the original deliberately strips
(an incoming replacement unmounts a streaming conversation and orphans its stream
mid-turn), and its quota guard returned void, so there was no record-count
watermark counterpart to `agenta:agent-chat:record-counts`.

Port `tabLocalStorage()`, the watermark store and its read atom, the
`{evicted, persisted}` quota-guard result, `persistSessionMessagesAtom`'s
`recordCount`, and the joint deletion path (exposed as a write atom here, since
the scope-keyed delete/close/prune callers stay in the app layer).
---
 .../agenta-chat/src/state/sessionMessages.ts  | 124 ++++++++++++++--
 .../tests/unit/state/sessionMessages.test.ts  | 138 +++++++++++++++++-
 2 files changed, 247 insertions(+), 15 deletions(-)

diff --git a/web/packages/agenta-chat/src/state/sessionMessages.ts b/web/packages/agenta-chat/src/state/sessionMessages.ts
index 5db480f549..35648f9f22 100644
--- a/web/packages/agenta-chat/src/state/sessionMessages.ts
+++ b/web/packages/agenta-chat/src/state/sessionMessages.ts
@@ -1,13 +1,21 @@
 // Copied from web/oss/src/components/AgentChatSlice/state/sessions.ts (2026-07-25) — ONLY the
 // self-contained message-persistence and run-status pieces the conversation host needs
-// (`sessionMessagesAtom`, the quota-guarded persist writer, and the per-session run-status
-// store). The OSS original remains authoritative for the desktop chat until the re-plumb PR
-// deletes it; keep byte-parity on the copied blocks if either side changes. The rest of that
-// file (scope-keyed history/tabs, server reconciliation, archive/delete remotes, timestamps)
-// is app-layer session-LIST state and stays out of the package deliberately.
+// (`sessionMessagesAtom` + its record watermark, the quota-guarded persist writer, and the
+// per-session run-status store). The OSS original remains authoritative for the desktop chat
+// until the re-plumb PR deletes it; keep byte-parity on the copied blocks if either side
+// changes. The rest of that file (scope-keyed history/tabs, server reconciliation,
+// archive/delete remotes, timestamps) is app-layer session-LIST state and stays out of the
+// package deliberately.
+//
+// Both copies write the SAME localStorage keys (`agenta:agent-chat:{messages,record-counts}`),
+// so a semantic difference here is a live defect the moment one app writes through the package
+// while the other reads OSS's stores. The ONE deliberate difference: OSS's `dropSessionMessages`
+// is a module-private helper called by its scope-keyed delete/close/prune paths, which do not
+// exist here — the package exposes the same joint deletion as a write atom
+// (`dropSessionMessagesAtom`) so a consumer that forgets a session cannot drop one store only.
 import type {UIMessage} from "ai"
-import {atom, type Setter} from "jotai"
-import {atomFamily, atomWithStorage} from "jotai/utils"
+import {atom, type Getter, type Setter} from "jotai"
+import {atomFamily, atomWithStorage, createJSONStorage} from "jotai/utils"
 
 import type {SessionRunStatus} from "../model/sessionStatus"
 
@@ -16,15 +24,47 @@ import type {SessionRunStatus} from "../model/sessionStatus"
 // read would see an empty store on every reload.
 const STORAGE_OPTS = {getOnInit: true} as const
 
+/**
+ * localStorage WITHOUT jotai's cross-browser-tab sync. The default storage subscribes to the
+ * `storage` event, so a write in one browser tab replaced these records live in every other one —
+ * and since the open-tab list drives the antd `Tabs` items, an incoming replacement UNMOUNTED a
+ * streaming conversation, orphaning its `useChat` stream mid-turn (the in-flight transcript is not
+ * persisted until the stream settles, so it was lost). Each browser tab now owns its view; storage
+ * is still shared, so a reload picks up whatever was last written.
+ */
+const tabLocalStorage = <T>() => {
+    const storage = createJSONStorage<T>()
+    delete storage.subscribe
+    return storage
+}
+
 /** Persisted messages per session id. Written when a conversation's stream settles. Session ids
  * are globally unique, so this store has no scope dimension. */
 export const sessionMessagesAtom = atomWithStorage<Record<string, UIMessage[]>>(
     "agenta:agent-chat:messages",
     {},
-    undefined,
+    tabLocalStorage(),
     STORAGE_OPTS,
 )
 
+/**
+ * Per-session adoption watermark: how many durable records the CACHED transcript above was built
+ * from. Absent means "not server-derived" (a locally-streamed turn, or a pre-#5530 cache) and reads
+ * as 0, so the next open re-syncs from the server once.
+ *
+ * Private on purpose — it must only ever move together with `sessionMessagesAtom`, so every write
+ * goes through `persistSessionMessagesAtom` and every delete through `dropSessionMessagesAtom`.
+ */
+const sessionRecordCountsAtom = atomWithStorage<Record<string, number>>(
+    "agenta:agent-chat:record-counts",
+    {},
+    tabLocalStorage(),
+    STORAGE_OPTS,
+)
+
+/** Read-only view of the watermarks; the guards read one non-reactively via `store.get`. */
+export const sessionRecordCountsReadAtom = atom((get) => get(sessionRecordCountsAtom))
+
 /** A localStorage-full error, across browsers (Chrome/Safari code 22, Firefox 1014). */
 const isQuotaExceeded = (e: unknown): boolean =>
     e instanceof DOMException &&
@@ -44,12 +84,13 @@ const writeMessagesWithQuotaGuard = (
     set: Setter,
     next: Record<string, UIMessage[]>,
     keepId: string,
-): void => {
+): {evicted: string[]; persisted: boolean} => {
     let candidate = next
+    const evicted: string[] = []
     for (;;) {
         try {
             set(sessionMessagesAtom, candidate)
-            return
+            return {evicted, persisted: true}
         } catch (e) {
             if (!isQuotaExceeded(e)) throw e
             // Object keys keep insertion order, so the first non-active id is the oldest.
@@ -57,19 +98,74 @@ const writeMessagesWithQuotaGuard = (
             if (oldest === undefined) {
                 // Even the active session alone won't fit — keep it in memory, skip persistence.
                 console.warn("[agent-chat] message store over quota; skipping persistence")
-                return
+                return {evicted, persisted: false}
             }
+            evicted.push(oldest)
             candidate = {...candidate}
             delete candidate[oldest]
         }
     }
 }
 
-/** Write a session's messages to the persisted store (called when its stream settles). */
+/**
+ * Drop cached transcripts AND their watermarks for `ids` — the two stores must never diverge, or a
+ * re-adopted session would be judged against a watermark belonging to a transcript that's gone.
+ * The single deletion path for both; every caller that forgets a session routes through here.
+ */
+const dropSessionMessages = (get: Getter, set: Setter, ids: string[]): void => {
+    if (ids.length === 0) return
+    const messages = {...get(sessionMessagesAtom)}
+    const counts = {...get(sessionRecordCountsAtom)}
+    let messagesChanged = false
+    let countsChanged = false
+    for (const id of ids) {
+        if (id in messages) {
+            delete messages[id]
+            messagesChanged = true
+        }
+        if (id in counts) {
+            delete counts[id]
+            countsChanged = true
+        }
+    }
+    if (messagesChanged) set(sessionMessagesAtom, messages)
+    if (countsChanged) set(sessionRecordCountsAtom, counts)
+}
+
+/** Forget the given sessions' cached transcripts and watermarks together. */
+export const dropSessionMessagesAtom = atom(null, (get, set, ids: string[]) => {
+    dropSessionMessages(get, set, ids)
+})
+
+/**
+ * Write a session's messages to the persisted store (called when its stream settles), together with
+ * the record watermark the transcript reflects. Pass `recordCount: undefined` for a locally-streamed
+ * transcript — we can't know how many records the server logged for it, and clearing the watermark
+ * makes the next open re-sync from the durable log rather than trust a stale number.
+ */
 export const persistSessionMessagesAtom = atom(
     null,
-    (get, set, {id, messages}: {id: string; messages: UIMessage[]}) => {
-        writeMessagesWithQuotaGuard(set, {...get(sessionMessagesAtom), [id]: messages}, id)
+    (
+        get,
+        set,
+        {id, messages, recordCount}: {id: string; messages: UIMessage[]; recordCount?: number},
+    ) => {
+        const {evicted, persisted} = writeMessagesWithQuotaGuard(
+            set,
+            {...get(sessionMessagesAtom), [id]: messages},
+            id,
+        )
+        const counts = {...get(sessionRecordCountsAtom)}
+        // If the transcript write itself was skipped (a single session over quota), the persisted
+        // store still holds the OLD messages — filing the NEW watermark against them would make
+        // `shouldAdoptServerTranscript` reject the complete server log as "not newer" on every
+        // future open, freezing the stale cache. The stores must never diverge (see
+        // `dropSessionMessages`), so drop the watermark and let the next open re-sync.
+        if (!persisted || recordCount === undefined) delete counts[id]
+        else counts[id] = recordCount
+        // A quota eviction dropped those transcripts, so their watermarks go too.
+        for (const evictedId of evicted) delete counts[evictedId]
+        set(sessionRecordCountsAtom, counts)
     },
 )
 
diff --git a/web/packages/agenta-chat/tests/unit/state/sessionMessages.test.ts b/web/packages/agenta-chat/tests/unit/state/sessionMessages.test.ts
index 9246248140..5f14624901 100644
--- a/web/packages/agenta-chat/tests/unit/state/sessionMessages.test.ts
+++ b/web/packages/agenta-chat/tests/unit/state/sessionMessages.test.ts
@@ -1,20 +1,49 @@
 // @vitest-environment jsdom
 import type {UIMessage} from "ai"
 import {createStore} from "jotai"
-import {describe, expect, it} from "vitest"
+import {afterEach, beforeEach, describe, expect, it, vi} from "vitest"
 
 import {
+    dropSessionMessagesAtom,
     isSessionStreamingAtomFamily,
     persistSessionMessagesAtom,
     sessionMessagesAtom,
+    sessionRecordCountsReadAtom,
     sessionStatusAtomFamily,
     setSessionStatusAtom,
 } from "../../../src/state/sessionMessages"
 
+const MESSAGES_KEY = "agenta:agent-chat:messages"
+const COUNTS_KEY = "agenta:agent-chat:record-counts"
+
 const msg = (id: string, text: string): UIMessage =>
     ({id, role: "user", parts: [{type: "text", text}]}) as UIMessage
 
+const quotaError = () => new DOMException("quota", "QuotaExceededError")
+
+/** Fail `localStorage.setItem` for the messages key while it holds more than `maxSessions`. */
+const failMessagesWriteOverQuota = (maxSessions: number) => {
+    const real = Storage.prototype.setItem
+    return vi.spyOn(Storage.prototype, "setItem").mockImplementation(function (
+        this: Storage,
+        key: string,
+        value: string,
+    ) {
+        if (key === MESSAGES_KEY && Object.keys(JSON.parse(value)).length > maxSessions) {
+            throw quotaError()
+        }
+        real.call(this, key, value)
+    })
+}
+
 describe("sessionMessages state", () => {
+    beforeEach(() => {
+        localStorage.clear()
+    })
+    afterEach(() => {
+        vi.restoreAllMocks()
+    })
+
     it("persists a session's messages under its id", () => {
         const store = createStore()
         store.set(persistSessionMessagesAtom, {id: "s1", messages: [msg("m1", "hello")]})
@@ -29,6 +58,113 @@ describe("sessionMessages state", () => {
         expect(store.get(sessionMessagesAtom)["s2"]).toHaveLength(1)
     })
 
+    // The OSS original deliberately strips jotai's cross-tab `storage` subscribe: an incoming
+    // replacement unmounted a streaming conversation and orphaned its `useChat` stream mid-turn.
+    // Both copies write the SAME key, so the package must not re-enable it.
+    it("does not sync across browser tabs — a foreign storage event never replaces the store", () => {
+        const store = createStore()
+        const unsub = store.sub(sessionMessagesAtom, () => {})
+        store.set(persistSessionMessagesAtom, {id: "s1", messages: [msg("m1", "mine")]})
+
+        // Another browser tab writes the shared key, then the browser fires `storage` here.
+        const foreign = JSON.stringify({s9: [msg("m9", "theirs")]})
+        localStorage.setItem(MESSAGES_KEY, foreign)
+        window.dispatchEvent(
+            new StorageEvent("storage", {
+                key: MESSAGES_KEY,
+                newValue: foreign,
+                storageArea: localStorage,
+            }),
+        )
+
+        expect(store.get(sessionMessagesAtom)["s1"]).toHaveLength(1)
+        expect(store.get(sessionMessagesAtom)["s9"]).toBeUndefined()
+        unsub()
+    })
+
+    it("files the record watermark alongside the transcript it was built from", () => {
+        const store = createStore()
+        store.set(persistSessionMessagesAtom, {
+            id: "s1",
+            messages: [msg("m1", "hello")],
+            recordCount: 7,
+        })
+        expect(store.get(sessionRecordCountsReadAtom)["s1"]).toBe(7)
+        expect(JSON.parse(localStorage.getItem(COUNTS_KEY) ?? "{}")["s1"]).toBe(7)
+    })
+
+    // A locally-streamed transcript has no known server record count; clearing the watermark makes
+    // the next open re-sync from the durable log instead of trusting a stale number.
+    it("clears the watermark when a settle persists without a record count", () => {
+        const store = createStore()
+        store.set(persistSessionMessagesAtom, {
+            id: "s1",
+            messages: [msg("m1", "hello")],
+            recordCount: 7,
+        })
+        store.set(persistSessionMessagesAtom, {id: "s1", messages: [msg("m1", "hello")]})
+        expect(store.get(sessionRecordCountsReadAtom)["s1"]).toBeUndefined()
+    })
+
+    it("drops a forgotten session's transcript and watermark together", () => {
+        const store = createStore()
+        store.set(persistSessionMessagesAtom, {
+            id: "s1",
+            messages: [msg("m1", "a")],
+            recordCount: 3,
+        })
+        store.set(persistSessionMessagesAtom, {
+            id: "s2",
+            messages: [msg("m2", "b")],
+            recordCount: 4,
+        })
+        store.set(dropSessionMessagesAtom, ["s1"])
+        expect(store.get(sessionMessagesAtom)["s1"]).toBeUndefined()
+        expect(store.get(sessionRecordCountsReadAtom)["s1"]).toBeUndefined()
+        expect(store.get(sessionMessagesAtom)["s2"]).toHaveLength(1)
+        expect(store.get(sessionRecordCountsReadAtom)["s2"]).toBe(4)
+    })
+
+    it("sheds an evicted session's watermark with its transcript when the store overflows", () => {
+        const store = createStore()
+        store.set(persistSessionMessagesAtom, {
+            id: "old",
+            messages: [msg("m1", "a")],
+            recordCount: 3,
+        })
+        // Only one session fits from here on, so persisting `new` evicts `old`.
+        failMessagesWriteOverQuota(1)
+        store.set(persistSessionMessagesAtom, {
+            id: "new",
+            messages: [msg("m2", "b")],
+            recordCount: 5,
+        })
+        expect(store.get(sessionMessagesAtom)["old"]).toBeUndefined()
+        expect(store.get(sessionRecordCountsReadAtom)["old"]).toBeUndefined()
+        expect(store.get(sessionMessagesAtom)["new"]).toHaveLength(1)
+        expect(store.get(sessionRecordCountsReadAtom)["new"]).toBe(5)
+    })
+
+    // The persisted store still holds the OLD messages, so filing the NEW watermark against them
+    // would make `shouldAdoptServerTranscript` reject the complete server log forever.
+    it("drops the watermark when even the active session will not fit", () => {
+        const store = createStore()
+        store.set(persistSessionMessagesAtom, {
+            id: "s1",
+            messages: [msg("m1", "a")],
+            recordCount: 3,
+        })
+        failMessagesWriteOverQuota(0)
+        const warn = vi.spyOn(console, "warn").mockImplementation(() => {})
+        store.set(persistSessionMessagesAtom, {
+            id: "s1",
+            messages: [msg("m2", "b")],
+            recordCount: 9,
+        })
+        expect(store.get(sessionRecordCountsReadAtom)["s1"]).toBeUndefined()
+        expect(warn).toHaveBeenCalled()
+    })
+
     it("run status defaults to idle, stores non-idle, and clears on idle", () => {
         const store = createStore()
         expect(store.get(sessionStatusAtomFamily("sx"))).toBe("idle")

From 480ce0fa8e56c632a72313f49753b4302cb54b42 Mon Sep 17 00:00:00 2001
From: Arda Erzin <ardaerzin@gmail.com>
Date: Sat, 1 Aug 2026 16:45:43 +0300
Subject: [PATCH 06/19] fix(mobile): derive the session liveness badge through
 the shared stream nest
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The badge read `flags.is_running` raw, so it disagreed with the desktop tab dot on
every row the coarse filter returns but the flags contradict: a flagless or
proc-dead (zombie) row was badged live, where the desktop dot reads it as idle.

Split on `deriveStreamNest` instead — running wins, then alive, everything else is
omitted — so both surfaces answer "running"/"alive" from one derivation. Polling
cadence and the react-query shape are untouched.
---
 .../src/features/sessions/useLivenessPoll.ts  | 17 +++++++++--
 web/mobile/tests/unit/livenessBadge.test.ts   | 28 +++++++++++++++++--
 2 files changed, 40 insertions(+), 5 deletions(-)

diff --git a/web/mobile/src/features/sessions/useLivenessPoll.ts b/web/mobile/src/features/sessions/useLivenessPoll.ts
index be75ca9f32..bfa5a6b023 100644
--- a/web/mobile/src/features/sessions/useLivenessPoll.ts
+++ b/web/mobile/src/features/sessions/useLivenessPoll.ts
@@ -1,4 +1,4 @@
-import {querySessionStreams, type SessionStream} from "@agenta/entities/session"
+import {deriveStreamNest, querySessionStreams, type SessionStream} from "@agenta/entities/session"
 import {useQuery} from "@tanstack/react-query"
 
 /** Shared key so other polls (interactions) can read the alive set from the cache. */
@@ -24,14 +24,25 @@ export const useLivenessPoll = (projectId: string) =>
 /** Coarse badge state for one session, derived from the shared poll. */
 export type SessionLivenessBadge = "running" | "alive"
 
-/** `session_id → badge` off the poll result; `undefined` while the poll hasn't resolved. */
+/**
+ * `session_id → badge` off the poll result; `undefined` while the poll hasn't resolved.
+ *
+ * Derived through the shared `deriveStreamNest`, never off `flags.is_running` directly, so this
+ * badge and the desktop tab dot (`oss AgentChatSlice state/liveness.ts`
+ * `sessionDotStatusAtomFamily`) split the same three flags the same way: running wins, then alive,
+ * and a proc-dead row the filter still returned (a zombie whose flags no longer say alive) is
+ * omitted — it reads as idle rather than being badged live. `deriveSessionLifecycle` is the same
+ * `isAlive` test today; it only starts saying more once the sandbox signal (#5197) is threaded in.
+ */
 export const livenessBySession = (
     streams: SessionStream[] | null | undefined,
 ): Map<string, SessionLivenessBadge> | undefined => {
     if (streams === undefined || streams === null) return undefined
     const map = new Map<string, SessionLivenessBadge>()
     for (const stream of streams) {
-        map.set(stream.session_id, stream.flags?.is_running ? "running" : "alive")
+        const nest = deriveStreamNest(stream)
+        if (nest.isRunning) map.set(stream.session_id, "running")
+        else if (nest.isAlive) map.set(stream.session_id, "alive")
     }
     return map
 }
diff --git a/web/mobile/tests/unit/livenessBadge.test.ts b/web/mobile/tests/unit/livenessBadge.test.ts
index b0b6baa444..4ff61ac66c 100644
--- a/web/mobile/tests/unit/livenessBadge.test.ts
+++ b/web/mobile/tests/unit/livenessBadge.test.ts
@@ -34,8 +34,32 @@ describe("livenessBySession", () => {
         expect(livenessBySession(null)).toBeUndefined()
     })
 
-    it("treats a flagless row as not running", () => {
+    // Parity with the desktop dot: the shared derivation defaults every flag to false, so a row
+    // with no live process reads as idle instead of being badged live off the poll's filter alone.
+    it("omits a flagless row rather than assuming it is alive", () => {
         const map = livenessBySession([stream("s-no-flags")])
-        expect(map?.get("s-no-flags")).toBe("alive")
+        expect(map?.has("s-no-flags")).toBe(false)
+    })
+
+    it("omits a zombie row whose flags no longer say alive", () => {
+        const map = livenessBySession([
+            stream("s-zombie", {is_alive: false, is_running: false, is_attached: false}),
+        ])
+        expect(map?.has("s-zombie")).toBe(false)
+    })
+
+    // `is_running` outranks a stale `is_alive` — the same precedence as `sessionDotStatusAtomFamily`.
+    it("badges a running row even if its alive flag lags behind", () => {
+        const map = livenessBySession([
+            stream("s-racing", {is_alive: false, is_running: true, is_attached: true}),
+        ])
+        expect(map?.get("s-racing")).toBe("running")
+    })
+
+    it("badges an attached-but-idle sandbox as live", () => {
+        const map = livenessBySession([
+            stream("s-attached", {is_alive: true, is_running: false, is_attached: true}),
+        ])
+        expect(map?.get("s-attached")).toBe("alive")
     })
 })

From a2aa64bc8fdbe9b152a0cccc2069d9255e6135d7 Mon Sep 17 00:00:00 2001
From: Arda Erzin <ardaerzin@gmail.com>
Date: Sat, 1 Aug 2026 17:09:31 +0300
Subject: [PATCH 07/19] fix(mobile): adopt the server transcript through the
 shared record watermark
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The chat screen hand-rolled its adoption logic on message counts alone, so it
missed the case the shared guard exists for: a turn that grows in place — tool
results landing, an approval round-trip completing — keeps its message count, and
mobile kept rendering the partial copy (issue #5530).

Mobile now calls `shouldAdoptServerTranscript`. Its inputs map as: `busy` is
always false (mobile never holds a live stream), and the watermark is an in-memory
ref rather than desktop's persisted record-counts store, since mobile caches no
transcript. The mapping lives in `transcriptAdoption.ts` so it is testable without
mounting the hook. The trailing-refresh queue, the cancellation flag and the
loading/ready/empty transitions are unchanged.

The guard needs a record count, so the package's `loadSessionMessages` regains the
`SessionTranscript` return its OSS original already carries (the copy is byte-identical
again below its header); `useAgentConversation` follows the new shape and now files
the record count with the transcripts it persists.
---
 .../src/features/chat/transcriptAdoption.ts   | 34 +++++++++
 .../src/features/chat/useSessionTranscript.ts | 70 +++++++++++++++----
 .../tests/unit/transcriptAdoption.test.ts     | 56 +++++++++++++++
 .../agenta-chat/src/assets/loadSession.ts     | 21 ++++--
 .../src/hooks/useAgentConversation.ts         | 31 +++++---
 .../tests/unit/assets/loadSession.test.ts     | 36 ++++++++--
 6 files changed, 211 insertions(+), 37 deletions(-)
 create mode 100644 web/mobile/src/features/chat/transcriptAdoption.ts
 create mode 100644 web/mobile/tests/unit/transcriptAdoption.test.ts

diff --git a/web/mobile/src/features/chat/transcriptAdoption.ts b/web/mobile/src/features/chat/transcriptAdoption.ts
new file mode 100644
index 0000000000..038cd2515e
--- /dev/null
+++ b/web/mobile/src/features/chat/transcriptAdoption.ts
@@ -0,0 +1,34 @@
+import type {SessionTranscript} from "@agenta/chat/assets"
+import {shouldAdoptServerTranscript} from "@agenta/entities/session"
+
+/** What the screen renders right now — the local half of the shared adoption rule. */
+export interface RenderedTranscript {
+    messageCount: number
+    /** Records the rendered transcript was built from; `undefined` before the first adoption. */
+    watermark: number | undefined
+}
+
+/**
+ * Should a delivered server transcript replace what the screen renders?
+ *
+ * The rule itself is the shared one (`shouldAdoptServerTranscript`, which desktop's
+ * `useSessionHydration` also calls) — the record log grew past our watermark, and the snapshot
+ * isn't shorter than what we show. Only the two inputs mobile has no direct equivalent for are
+ * filled in here:
+ *   - `busy` is always false: mobile is read-only, it never holds a live `useChat` stream that
+ *     could outrank the durable log.
+ *   - the watermark is the hook's in-memory one, not desktop's persisted
+ *     `agenta:agent-chat:record-counts` — mobile caches no transcript, so it re-syncs on open.
+ */
+export const shouldAdoptTranscript = (
+    transcript: SessionTranscript | null,
+    rendered: RenderedTranscript,
+): boolean =>
+    transcript !== null &&
+    shouldAdoptServerTranscript({
+        serverRecordCount: transcript.recordCount,
+        serverMessageCount: transcript.messages.length,
+        localMessageCount: rendered.messageCount,
+        watermark: rendered.watermark,
+        busy: false,
+    })
diff --git a/web/mobile/src/features/chat/useSessionTranscript.ts b/web/mobile/src/features/chat/useSessionTranscript.ts
index 7af13f5473..5e9ddb867e 100644
--- a/web/mobile/src/features/chat/useSessionTranscript.ts
+++ b/web/mobile/src/features/chat/useSessionTranscript.ts
@@ -1,10 +1,12 @@
 import {useCallback, useEffect, useRef, useState} from "react"
 
-import {loadSessionMessages} from "@agenta/chat/assets"
+import {loadSessionMessages, type SessionTranscript} from "@agenta/chat/assets"
 import {revalidateSessionRecordsAtom} from "@agenta/entities/session"
 import type {UIMessage} from "ai"
 import {getDefaultStore} from "jotai"
 
+import {shouldAdoptTranscript} from "./transcriptAdoption"
+
 /**
  * Read-only transcript for one session: server record replay via `loadSessionMessages`
  * (IndexedDB-restored, revalidation re-delivered through `onRefreshed`). `null` history
@@ -28,23 +30,61 @@ export const useSessionTranscript = (sessionId: string, pollMs = 0) => {
     // can strand the FINAL transcript state forever (the turn's `ended` also kills the
     // tightened poll, so nothing else would ever re-read).
     const pendingRef = useRef(false)
+    // What is on screen, read by the adoption guard: `messages` state lags a commit behind, so
+    // two deliveries landing back-to-back would both see the pre-adoption transcript.
+    const messagesRef = useRef<UIMessage[]>([])
+    // Records the rendered transcript was built from; `undefined` until the first adoption. This
+    // is in-memory only — mobile persists no transcript, so there is nothing to file it against.
+    const watermarkRef = useRef<number | undefined>(undefined)
+
+    /**
+     * Apply one delivery behind the shared adoption rule (`shouldAdoptTranscript`). Returns
+     * whether it adopted, so callers can tell "nothing on the server" from "already up to date".
+     */
+    const adopt = useCallback(
+        (transcript: SessionTranscript | null): boolean => {
+            // A late resolve for a previous session must never land.
+            if (sessionRef.current !== sessionId) return false
+            const shouldAdopt = shouldAdoptTranscript(transcript, {
+                messageCount: messagesRef.current.length,
+                watermark: watermarkRef.current,
+            })
+            if (!shouldAdopt || !transcript) return false
+            watermarkRef.current = transcript.recordCount
+            messagesRef.current = transcript.messages
+            setMessages(transcript.messages)
+            setState("ready")
+            return true
+        },
+        [sessionId],
+    )
+    // The poll/relay refresh below must not re-arm on every render, so it reads the current
+    // adopter through a ref rather than closing over it.
+    const adoptRef = useRef(adopt)
+    adoptRef.current = adopt
 
     useEffect(() => {
         let cancelled = false
-        let refreshed = false
+        // A fast revalidation can beat the one-shot resolve; the watermark keeps the two
+        // deliveries order-independent, and this flag keeps a stale empty result from blanking
+        // a transcript the revalidation already adopted.
+        let adopted = false
         setState("loading")
         setMessages([])
+        messagesRef.current = []
+        watermarkRef.current = undefined
         void loadSessionMessages(sessionId, (fresh) => {
             // Disk-restore revalidation re-delivery — fresh is non-empty by contract.
             if (cancelled) return
-            refreshed = true
-            setMessages(fresh)
-            setState("ready")
-        }).then((msgs) => {
-            // A fast revalidation can beat this one-shot resolve; never clobber it.
-            if (cancelled || refreshed) return
-            setMessages(msgs ?? [])
-            setState(msgs && msgs.length > 0 ? "ready" : "empty")
+            if (adoptRef.current(fresh)) adopted = true
+        }).then((transcript) => {
+            if (cancelled) return
+            if (adoptRef.current(transcript)) {
+                adopted = true
+                return
+            }
+            // Nothing adopted from either delivery → no durable history for this session.
+            if (!adopted) setState("empty")
         })
         return () => {
             cancelled = true
@@ -61,12 +101,12 @@ export const useSessionTranscript = (sessionId: string, pollMs = 0) => {
         // Invalidate first so the shared-cache read refetches instead of serving staleTime.
         getDefaultStore().set(revalidateSessionRecordsAtom, sessionId)
         void loadSessionMessages(sessionId)
-            .then((msgs) => {
-                if (sessionRef.current === sessionId && msgs && msgs.length > 0) {
-                    setMessages(msgs)
-                    setState("ready")
-                }
+            .then((transcript) => {
+                adoptRef.current(transcript)
             })
+            // A failed poll keeps what is on screen and waits for the next tick; swallowing it
+            // here keeps a transient 5xx from surfacing as an unhandled rejection every 3s.
+            .catch(() => undefined)
             .finally(() => {
                 inFlightRef.current = false
                 if (pendingRef.current) {
diff --git a/web/mobile/tests/unit/transcriptAdoption.test.ts b/web/mobile/tests/unit/transcriptAdoption.test.ts
new file mode 100644
index 0000000000..30de438592
--- /dev/null
+++ b/web/mobile/tests/unit/transcriptAdoption.test.ts
@@ -0,0 +1,56 @@
+import type {SessionTranscript} from "@agenta/chat/assets"
+import type {UIMessage} from "ai"
+import {describe, expect, it} from "vitest"
+
+import {shouldAdoptTranscript} from "../../src/features/chat/transcriptAdoption"
+
+const transcript = (messageCount: number, recordCount: number): SessionTranscript => ({
+    messages: Array.from(
+        {length: messageCount},
+        (_, i) => ({id: `m${i}`, role: "assistant", parts: []}) as UIMessage,
+    ),
+    recordCount,
+})
+
+describe("shouldAdoptTranscript", () => {
+    it("adopts the first delivery for a freshly opened session", () => {
+        expect(
+            shouldAdoptTranscript(transcript(3, 12), {messageCount: 0, watermark: undefined}),
+        ).toBe(true)
+    })
+
+    it("ignores a failed / history-less load", () => {
+        expect(shouldAdoptTranscript(null, {messageCount: 0, watermark: undefined})).toBe(false)
+        expect(
+            shouldAdoptTranscript(transcript(0, 0), {messageCount: 0, watermark: undefined}),
+        ).toBe(false)
+    })
+
+    it("ignores a re-read that brought no new records", () => {
+        expect(shouldAdoptTranscript(transcript(3, 12), {messageCount: 3, watermark: 12})).toBe(
+            false,
+        )
+    })
+
+    // Issue #5530: a turn that grows in place (tool results landing, an approval round-trip
+    // completing) keeps its message count, so only the record watermark sees the growth.
+    it("adopts a grown log even when the message count is unchanged", () => {
+        expect(shouldAdoptTranscript(transcript(3, 40), {messageCount: 3, watermark: 12})).toBe(
+            true,
+        )
+    })
+
+    it("never trades down to a snapshot shorter than what is on screen", () => {
+        expect(shouldAdoptTranscript(transcript(2, 40), {messageCount: 3, watermark: 12})).toBe(
+            false,
+        )
+    })
+
+    // Mobile keeps no persisted transcript, so a session it has rendered before still opens with
+    // an absent watermark — which reads as 0 and re-syncs from the durable log once.
+    it("re-syncs when the watermark is absent", () => {
+        expect(
+            shouldAdoptTranscript(transcript(3, 12), {messageCount: 3, watermark: undefined}),
+        ).toBe(true)
+    })
+})
diff --git a/web/packages/agenta-chat/src/assets/loadSession.ts b/web/packages/agenta-chat/src/assets/loadSession.ts
index 31bcecfcd6..ef624a5288 100644
--- a/web/packages/agenta-chat/src/assets/loadSession.ts
+++ b/web/packages/agenta-chat/src/assets/loadSession.ts
@@ -27,10 +27,20 @@ import {transcriptToMessages} from "./transcriptToMessages"
  * authoritative). Because this return is a one-shot copy, `onRefreshed` re-delivers the
  * transcript when that revalidation lands — callers apply it behind their own adoption guards.
  */
+export interface SessionTranscript {
+    messages: UIMessage[]
+    /**
+     * How many durable records this transcript was built from. The log is append-only and ordered,
+     * so this is an EXACT "has the server moved on?" watermark — unlike a message count, which
+     * `transcriptToMessages` deliberately holds flat while a turn grows (issue #5530).
+     */
+    recordCount: number
+}
+
 export const loadSessionMessages = async (
     sessionId: string,
-    onRefreshed?: (messages: UIMessage[]) => void,
-): Promise<UIMessage[] | null> => {
+    onRefreshed?: (transcript: SessionTranscript) => void,
+): Promise<SessionTranscript | null> => {
     // Fetch through the shared records query cache (same key as `sessionRecordsQueryFamily`) so
     // hydration, revalidation, and the Inspector's atom subscribers share ONE network flight per
     // stale window instead of each issuing a raw duplicate request. A failure resolves to `null`
@@ -43,7 +53,9 @@ export const loadSessionMessages = async (
                 .then((fresh) => {
                     if (!fresh || fresh.length === 0) return
                     const freshMsgs = transcriptToMessages(fresh)
-                    if (freshMsgs && freshMsgs.length > 0) onRefreshed(freshMsgs)
+                    if (freshMsgs && freshMsgs.length > 0) {
+                        onRefreshed({messages: freshMsgs, recordCount: fresh.length})
+                    }
                 })
                 // This chain outlives the function, so the try/catch below cannot see it. A
                 // failed revalidation keeps whatever the cache already restored; without this
@@ -53,7 +65,8 @@ export const loadSessionMessages = async (
                 })
         }
         if (!records || records.length === 0) return null
-        return transcriptToMessages(records)
+        const messages = transcriptToMessages(records)
+        return messages ? {messages, recordCount: records.length} : null
     } catch (err) {
         console.warn("[loadSessionMessages] hydration fetch failed:", err)
         return null
diff --git a/web/packages/agenta-chat/src/hooks/useAgentConversation.ts b/web/packages/agenta-chat/src/hooks/useAgentConversation.ts
index 104506e2aa..612eb5a0ff 100644
--- a/web/packages/agenta-chat/src/hooks/useAgentConversation.ts
+++ b/web/packages/agenta-chat/src/hooks/useAgentConversation.ts
@@ -29,7 +29,7 @@ import type {UIMessage} from "ai"
 import {useSetAtom, useStore} from "jotai"
 
 import {filesToParts} from "../assets/files"
-import {loadSessionMessages} from "../assets/loadSession"
+import {loadSessionMessages, type SessionTranscript} from "../assets/loadSession"
 import {messageText, sideEffectingToolsInRange} from "../assets/rewind"
 import {getMessageTraceId} from "../assets/trace"
 import {parseAgentRunError, type ParsedRunError} from "../model/error"
@@ -266,27 +266,31 @@ export const useAgentConversation = ({
         // Post-restore revalidation: the first result may be the disk-restored log (paints
         // instantly); when the guaranteed background refetch lands, adopt it under the same
         // guards as the revalidate-on-open effect below — never mid-stream, only when ahead.
-        const adoptRefreshed = (freshMsgs: UIMessage[]) => {
+        const adoptRefreshed = ({messages: freshMsgs, recordCount}: SessionTranscript) => {
             if (cancelled || busyRef.current) return
             if (freshMsgs.length <= messagesRef.current.length) return
             freshMsgs.forEach((m) => restoredIdsRef.current.add(m.id))
             // The restore said "no records" but the server has some — clear the notice.
             setHistoryUnavailable(false)
             setMessages(freshMsgs)
-            persistMessages({id: sessionId, messages: freshMsgs})
+            persistMessages({id: sessionId, messages: freshMsgs, recordCount})
         }
         loadSessionMessages(sessionId, adoptRefreshed)
-            .then((msgs) => {
+            .then((transcript) => {
                 if (cancelled) return
-                if (!msgs || msgs.length === 0) {
+                if (!transcript || transcript.messages.length === 0) {
                     // Known session, but the server has no records for it → history was pruned or
                     // never persisted. Flag it so the skin shows the "unavailable" notice.
                     setHistoryUnavailable(true)
                     return
                 }
-                msgs.forEach((m) => restoredIdsRef.current.add(m.id))
-                setMessages(msgs)
-                persistMessages({id: sessionId, messages: msgs})
+                transcript.messages.forEach((m) => restoredIdsRef.current.add(m.id))
+                setMessages(transcript.messages)
+                persistMessages({
+                    id: sessionId,
+                    messages: transcript.messages,
+                    recordCount: transcript.recordCount,
+                })
             })
             .finally(() => {
                 if (!cancelled) setIsHydrating(false)
@@ -306,13 +310,18 @@ export const useAgentConversation = ({
         if (initialMessages.length === 0 || isSessionFresh(sessionId)) return
         // As above: no persistent ref, so StrictMode's double-mount re-runs the revalidation.
         let cancelled = false
-        const adopt = (serverMsgs: UIMessage[] | null) => {
-            if (cancelled || !serverMsgs || serverMsgs.length === 0) return
+        const adopt = (transcript: SessionTranscript | null) => {
+            if (cancelled || !transcript || transcript.messages.length === 0) return
+            const serverMsgs = transcript.messages
             const prev = messagesRef.current
             if (busyRef.current || serverMsgs.length <= prev.length) return
             serverMsgs.forEach((m) => restoredIdsRef.current.add(m.id))
             setMessages(serverMsgs)
-            persistMessages({id: sessionId, messages: serverMsgs})
+            persistMessages({
+                id: sessionId,
+                messages: serverMsgs,
+                recordCount: transcript.recordCount,
+            })
         }
         // The first result may itself be the disk-restored records log; the callback re-applies
         // the same guarded adoption when the guaranteed background revalidation lands.
diff --git a/web/packages/agenta-chat/tests/unit/assets/loadSession.test.ts b/web/packages/agenta-chat/tests/unit/assets/loadSession.test.ts
index 9f6082f168..ab85a64503 100644
--- a/web/packages/agenta-chat/tests/unit/assets/loadSession.test.ts
+++ b/web/packages/agenta-chat/tests/unit/assets/loadSession.test.ts
@@ -42,9 +42,24 @@ describe("loadSessionMessages", () => {
         fetchResult = {
             records: [record("r1", {type: "message", text: "hi"}), record("r2", {type: "done"})],
         }
-        const messages = await loadSessionMessages("session-1")
-        expect(messages).toHaveLength(1)
-        expect(messages?.[0]).toMatchObject({parts: [{type: "text", text: "hi"}]})
+        const transcript = await loadSessionMessages("session-1")
+        expect(transcript?.messages).toHaveLength(1)
+        expect(transcript?.messages[0]).toMatchObject({parts: [{type: "text", text: "hi"}]})
+    })
+
+    // The adoption watermark: records, not messages — a turn that grows in place keeps its
+    // message count (issue #5530), so only this number sees the log move.
+    it("reports how many records the transcript was built from", async () => {
+        fetchResult = {
+            records: [
+                record("r1", {type: "message", text: "hi"}),
+                record("r2", {type: "message", text: " there"}),
+                record("r3", {type: "done"}),
+            ],
+        }
+        const transcript = await loadSessionMessages("session-1")
+        expect(transcript?.messages).toHaveLength(1)
+        expect(transcript?.recordCount).toBe(3)
     })
 
     it("delivers a refreshed transcript via onRefreshed once the background revalidation resolves", async () => {
@@ -59,8 +74,13 @@ describe("loadSessionMessages", () => {
         await Promise.resolve()
         await Promise.resolve()
         expect(onRefreshed).toHaveBeenCalledTimes(1)
-        const delivered = onRefreshed.mock.calls[0][0] as {parts: unknown}[]
-        expect(delivered[0]).toMatchObject({parts: [{type: "text", text: "fresh"}]})
+        const delivered = onRefreshed.mock.calls[0][0] as {
+            messages: {parts: unknown}[]
+            recordCount: number
+        }
+        expect(delivered.messages[0]).toMatchObject({parts: [{type: "text", text: "fresh"}]})
+        // The refreshed delivery carries the FRESH log's count, not the stale one's.
+        expect(delivered.recordCount).toBe(2)
     })
 
     // The chain outlives the call, so the function's own try/catch never sees a rejection here.
@@ -77,11 +97,13 @@ describe("loadSessionMessages", () => {
                 refreshed: Promise.reject(new Error("boom")),
             }
             const onRefreshed = vi.fn()
-            const messages = await loadSessionMessages("session-1", onRefreshed)
+            const transcript = await loadSessionMessages("session-1", onRefreshed)
             await Promise.resolve()
             await Promise.resolve()
             // The restored transcript still stands; only the revalidation was lost.
-            expect(messages?.[0]).toMatchObject({parts: [{type: "text", text: "stale"}]})
+            expect(transcript?.messages[0]).toMatchObject({
+                parts: [{type: "text", text: "stale"}],
+            })
             expect(onRefreshed).not.toHaveBeenCalled()
             expect(warn).toHaveBeenCalled()
             await new Promise((resolve) => setTimeout(resolve, 0))

From 185c875a40bb3c9434e84ca704cf3f74f720c582 Mon Sep 17 00:00:00 2001
From: Arda Erzin <ardaerzin@gmail.com>
Date: Sun, 2 Aug 2026 22:56:36 +0300
Subject: [PATCH 08/19] feat(mobile): brand sign-in, pin every header, and make
 the workspace switchable
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Sign-in and the OIDC callback carry the Agenta wordmark, inlined rather than
served from public/ (a bare <img src="/assets/..."> misses the /m basePath) and
drawn in currentColor so one component covers both themes.

Header pinning becomes one ScreenScaffold instead of a shape hand-copied per
screen: a h-dvh column whose middle is the only scroller. The project picker never
had it and scrolled its own title away. The chat dock is passed as a footer only
when it renders, so the scaffold's safe-area rule holds instead of silently
lapsing when no gate is pending.

The workspace line is now a real selector: chips when there are several, a labelled
name when there is one (the default workspace is called "Default", indistinguishable
from a project of that name). Reaching the picker at all needed ?switch=1, since a
stored context auto-forwards past it — and that decision is gated on router.isReady,
without which the first render forwards before the switch intent is knowable.

Signed-out copy no longer claims you signed out on a screen that also renders for
someone who never signed in.
---
 web/mobile/src/components/AgentaLogo.tsx      |  23 ++++
 web/mobile/src/components/ScreenScaffold.tsx  |  42 ++++++++
 .../src/features/auth/OidcCallbackScreen.tsx  |   4 +-
 web/mobile/src/features/auth/SignInScreen.tsx |   8 +-
 web/mobile/src/features/chat/ChatScreen.tsx   |  47 +++++---
 .../src/features/context/ContextResolver.tsx  |  66 ++++++------
 .../src/features/context/ProjectSwitcher.tsx  |  46 ++++++++
 .../features/context/WorkspaceProjectList.tsx |  93 +++++++++++-----
 .../src/features/context/contextTarget.ts     |  46 ++++++++
 .../context/states/SignedOutNotice.tsx        |   4 +-
 .../features/sessions/SessionListScreen.tsx   |  37 ++++---
 web/mobile/tests/unit/contextTarget.test.ts   | 100 ++++++++++++++++++
 12 files changed, 417 insertions(+), 99 deletions(-)
 create mode 100644 web/mobile/src/components/AgentaLogo.tsx
 create mode 100644 web/mobile/src/components/ScreenScaffold.tsx
 create mode 100644 web/mobile/src/features/context/ProjectSwitcher.tsx
 create mode 100644 web/mobile/src/features/context/contextTarget.ts
 create mode 100644 web/mobile/tests/unit/contextTarget.test.ts

diff --git a/web/mobile/src/components/AgentaLogo.tsx b/web/mobile/src/components/AgentaLogo.tsx
new file mode 100644
index 0000000000..eb816a7e93
--- /dev/null
+++ b/web/mobile/src/components/AgentaLogo.tsx
@@ -0,0 +1,23 @@
+interface AgentaLogoProps {
+    className?: string
+}
+
+/**
+ * Agenta wordmark, inlined from `web/oss/public/assets/logos/Agenta-logo-full-light.svg`.
+ *
+ * Inlined rather than served from `public/`: a bare `<img src="/assets/...">` misses the app's
+ * `/m` basePath, and the desktop app swaps two files by theme. `currentColor` gets both for
+ * free — the mark takes whatever text color it inherits, in either theme.
+ */
+export const AgentaLogo = ({className}: AgentaLogoProps) => (
+    <svg
+        viewBox="0 0 361 80"
+        role="img"
+        aria-label="Agenta"
+        fill="currentColor"
+        className={className}
+    >
+        <path d="M58.7822 48.8226C58.6386 50.0974 59.344 50.4695 60.3941 49.9879C63.5068 48.5604 75.9579 42.066 82.6216 42.066C84.8183 42.066 93.662 43.1149 76.2557 60.0108C61.611 74.2261 57.6428 71.1651 56.6105 70.1327C53.8889 67.4111 55.3791 59.9499 55.8364 56.2118C56.0011 54.8654 55.5404 54.4469 54.236 55.03C42.4998 60.2773 20.569 71.2489 8.39828 71.2489C-14.9334 71.2489 17.2232 33.0373 22.2267 26.9551C38.8349 6.76618 49.5549 0 55.5916 0C66.5225 0 62.0341 19.9537 58.7822 48.8226Z" />
+        <path d="M110.312 63.9121L129.602 9.6792H139.794L159.449 63.9121H150.459L139.903 33.7381C139.078 31.2875 138.174 28.4004 137.191 25.0756C136.209 21.7517 135.074 17.7598 133.788 13.1005H135.462C134.225 17.8085 133.115 21.8426 132.132 25.2028C131.149 28.5639 130.282 31.4087 129.53 33.7381L119.302 63.9121H110.312ZM120.758 49.6076V42.692H148.966V49.6076H120.758ZM183.107 79.9998C179.977 79.9998 177.259 79.5997 174.954 78.799C172.649 77.9979 170.75 76.9298 169.258 75.5959C167.765 74.261 166.631 72.7804 165.855 71.1553L172.552 67.9884C173.037 68.7647 173.686 69.5838 174.499 70.4456C175.312 71.3064 176.41 72.0409 177.793 72.6477C179.176 73.2536 180.947 73.5577 183.107 73.5577C186.213 73.5577 188.731 72.8232 190.66 71.3556C192.589 69.8869 193.553 67.5883 193.553 64.4583V56.5233H192.862C192.376 57.4214 191.703 58.392 190.842 59.4352C189.98 60.4789 188.779 61.3824 187.239 62.1468C185.697 62.9111 183.69 63.2933 181.215 63.2933C178.011 63.2933 175.13 62.5414 172.57 61.0365C170.01 59.5326 167.978 57.3001 166.474 54.3395C164.969 51.3794 164.217 47.7394 164.217 43.4201C164.217 39.1012 164.963 35.3946 166.455 32.3003C167.948 29.2066 169.986 26.8354 172.57 25.1849C175.154 23.5349 178.072 22.7099 181.324 22.7099C183.823 22.7099 185.855 23.1229 187.421 23.9474C188.986 24.7724 190.211 25.749 191.097 26.8772C191.982 28.0058 192.655 28.9948 193.117 29.8437H193.699V23.2193H201.525V64.4946C201.525 68.0615 200.718 70.9913 199.104 73.2844C197.49 75.5775 195.294 77.2703 192.516 78.3622C189.737 79.4541 186.601 79.9998 183.107 79.9998ZM183.071 56.6326C185.352 56.6326 187.275 56.1048 188.84 55.0492C190.405 53.9936 191.588 52.4648 192.389 50.463C193.19 48.4611 193.59 46.077 193.59 43.3107C193.59 40.5693 193.19 38.1668 192.389 36.1043C191.588 34.0418 190.405 32.4281 188.84 31.2631C187.275 30.0987 185.352 29.5162 183.071 29.5162C180.717 29.5162 178.751 30.129 177.175 31.3541C175.597 32.5797 174.408 34.2297 173.608 36.3041C172.807 38.3791 172.406 40.7149 172.406 43.3107C172.406 45.9562 172.807 48.2792 173.608 50.2811C174.408 52.2829 175.603 53.8425 177.193 54.9583C178.782 56.0745 180.741 56.6326 183.071 56.6326ZM229.842 64.749C225.839 64.749 222.381 63.8882 219.469 62.1652C216.557 60.4426 214.318 58.0158 212.753 54.8852C211.188 51.7551 210.405 48.0789 210.405 43.8569C210.405 39.6837 211.176 36.0074 212.717 32.8281C214.258 29.6499 216.435 27.1684 219.25 25.3852C222.065 23.6015 225.365 22.7099 229.151 22.7099C231.48 22.7099 233.724 23.0921 235.884 23.8564C238.044 24.6208 239.985 25.8161 241.708 27.4412C243.431 29.0674 244.795 31.1722 245.802 33.7565C246.809 36.3409 247.313 39.4774 247.313 43.1651V46.0044H214.882V40.035H243.2L239.451 42.0007C239.451 39.5018 239.063 37.2996 238.286 35.3946C237.509 33.4896 236.363 32.0036 234.847 30.9356C233.33 29.8681 231.431 29.3343 229.151 29.3343C226.894 29.3343 224.965 29.88 223.363 30.9719C221.762 32.0638 220.543 33.5016 219.705 35.2853C218.868 37.0685 218.45 39.0162 218.45 41.1269V45.2038C218.45 47.9944 218.928 50.3541 219.887 52.2829C220.846 54.2123 222.186 55.668 223.909 56.6505C225.632 57.6336 227.634 58.1246 229.915 58.1246C231.419 58.1246 232.778 57.9129 233.991 57.488C235.204 57.0635 236.254 56.4204 237.14 55.5586C238.025 54.6978 238.699 53.6358 239.16 52.3739L246.694 54.1576C246.039 56.2445 244.941 58.0883 243.4 59.6901C241.859 61.2914 239.942 62.5354 237.65 63.4206C235.357 64.3062 232.754 64.749 229.842 64.749ZM264.093 39.8169V63.9121H256.085V23.2193H263.765V33.1924H262.964C264.153 29.5525 265.876 26.8955 268.133 25.2212C270.389 23.5468 273.119 22.7099 276.322 22.7099C279.088 22.7099 281.502 23.2923 283.565 24.4568C285.627 25.6217 287.242 27.3384 288.406 29.6071C289.571 31.8764 290.153 34.6973 290.153 38.0694V63.9121H282.146V39.0525C282.146 36.1168 281.382 33.8236 279.853 32.1731C278.324 30.5231 276.225 29.6981 273.556 29.6981C271.76 29.6981 270.147 30.0927 268.715 30.8809C267.283 31.6697 266.155 32.8162 265.33 34.3206C264.505 35.8255 264.093 37.6574 264.093 39.8169ZM318.326 23.2193V29.7344H296.268V23.2193H318.326ZM302.201 13.5374H310.209V52.9201C310.209 54.5458 310.555 55.741 311.246 56.5049C311.938 57.2693 313.071 57.6515 314.649 57.6515C315.061 57.6515 315.607 57.6033 316.287 57.5058C316.966 57.4094 317.548 57.312 318.034 57.2151L319.454 63.6209C318.604 63.9121 317.694 64.1243 316.724 64.258C315.753 64.3912 314.795 64.4583 313.848 64.4583C310.159 64.4583 307.297 63.506 305.259 61.6011C303.22 59.6961 302.201 57.0208 302.201 53.5751V13.5374ZM340.673 64.7127C337.398 64.7127 334.479 63.8698 331.92 62.1831C329.359 60.4968 327.345 58.0829 325.878 54.9399C324.409 51.7979 323.676 48.0426 323.676 43.675C323.676 39.2587 324.422 35.4856 325.914 32.355C327.407 29.2249 329.445 26.8354 332.029 25.1849C334.613 23.5349 337.531 22.7099 340.783 22.7099C343.282 22.7099 345.302 23.1229 346.843 23.9474C348.384 24.7724 349.584 25.749 350.446 26.8772C351.307 28.0058 351.968 28.9948 352.43 29.8437H352.94V23.2193H360.874V63.9121H352.976V57.5426H352.43C351.968 58.4158 351.289 59.4168 350.392 60.5455C349.493 61.6736 348.268 62.6507 346.715 63.4752C345.162 64.2997 343.148 64.7127 340.673 64.7127ZM342.53 57.9064C344.81 57.9064 346.734 57.3001 348.299 56.0864C349.864 54.8733 351.047 53.1929 351.848 51.0454C352.648 48.8979 353.048 46.4174 353.048 43.602C353.048 40.7631 352.648 38.2941 351.848 36.1953C351.047 34.0965 349.864 32.4589 348.299 31.2815C346.734 30.1046 344.81 29.5162 342.53 29.5162C340.176 29.5162 338.21 30.129 336.633 31.3541C335.056 32.5797 333.867 34.254 333.066 36.3772C332.266 38.5008 331.865 40.9088 331.865 43.602C331.865 46.2957 332.266 48.7225 333.066 50.8814C333.867 53.0419 335.062 54.7525 336.652 56.0139C338.241 57.2757 340.2 57.9064 342.53 57.9064Z" />
+    </svg>
+)
diff --git a/web/mobile/src/components/ScreenScaffold.tsx b/web/mobile/src/components/ScreenScaffold.tsx
new file mode 100644
index 0000000000..a182595b07
--- /dev/null
+++ b/web/mobile/src/components/ScreenScaffold.tsx
@@ -0,0 +1,42 @@
+import type {ReactNode, RefObject, UIEventHandler} from "react"
+
+interface ScreenScaffoldProps {
+    /** Pinned above the scroller. Never scrolls away. */
+    header?: ReactNode
+    /** Pinned below the scroller (approval dock, composer). */
+    footer?: ReactNode
+    scrollRef?: RefObject<HTMLDivElement | null>
+    onScroll?: UIEventHandler<HTMLDivElement>
+    children: ReactNode
+}
+
+/**
+ * The one mobile screen shape: a viewport-height column whose header and footer are pinned and
+ * whose middle is the ONLY scroller.
+ *
+ * `h-dvh` + an `overflow-y-auto` middle keeps scrolling inside the list rather than the
+ * document — a `min-h-dvh` page scrolls its own header off-screen on iOS, which is the bug this
+ * exists to prevent. The bottom-most element owns the safe-area inset, so the scroller only
+ * pads for it when there is no footer.
+ */
+export const ScreenScaffold = ({
+    header,
+    footer,
+    scrollRef,
+    onScroll,
+    children,
+}: ScreenScaffoldProps) => (
+    <div className="bg-background text-foreground flex h-dvh flex-col">
+        {header}
+        <div
+            ref={scrollRef}
+            onScroll={onScroll}
+            className={`flex flex-1 flex-col overflow-y-auto overscroll-contain${
+                footer ? "" : " pb-[env(safe-area-inset-bottom)]"
+            }`}
+        >
+            {children}
+        </div>
+        {footer}
+    </div>
+)
diff --git a/web/mobile/src/features/auth/OidcCallbackScreen.tsx b/web/mobile/src/features/auth/OidcCallbackScreen.tsx
index cb2c5e7b85..8a392a7ea4 100644
--- a/web/mobile/src/features/auth/OidcCallbackScreen.tsx
+++ b/web/mobile/src/features/auth/OidcCallbackScreen.tsx
@@ -3,6 +3,7 @@ import {useEffect, useRef, useState} from "react"
 import Link from "next/link"
 import {useRouter} from "next/router"
 
+import {AgentaLogo} from "@/components/AgentaLogo"
 import {completeOidcSignIn} from "@/lib/auth"
 
 import {useAuthSuccess} from "./useAuthSuccess"
@@ -40,7 +41,8 @@ export const OidcCallbackScreen = () => {
     }, [router, router.isReady, onSuccess])
 
     return (
-        <div className="bg-background text-foreground flex min-h-dvh flex-col items-center justify-center gap-3 p-6 text-center">
+        <div className="bg-background text-foreground flex min-h-dvh flex-col items-center justify-center gap-6 p-6 text-center">
+            <AgentaLogo className="text-foreground h-6 w-auto" />
             {error ? (
                 <>
                     <p className="text-destructive text-xs" role="alert">
diff --git a/web/mobile/src/features/auth/SignInScreen.tsx b/web/mobile/src/features/auth/SignInScreen.tsx
index cbf186002e..6088cd4d45 100644
--- a/web/mobile/src/features/auth/SignInScreen.tsx
+++ b/web/mobile/src/features/auth/SignInScreen.tsx
@@ -1,5 +1,6 @@
 import {useEffect, useState} from "react"
 
+import {AgentaLogo} from "@/components/AgentaLogo"
 import {
     getEmailSignInMode,
     isOidcEnabled,
@@ -66,8 +67,11 @@ export const SignInScreen = () => {
     }
 
     return (
-        <div className="bg-background text-foreground flex min-h-dvh flex-col items-center justify-center gap-4 p-6">
-            <p className="text-sm font-medium">Sign in to Agenta</p>
+        <div className="bg-background text-foreground flex min-h-dvh flex-col items-center justify-center gap-8 p-6">
+            <header className="flex flex-col items-center gap-3">
+                <AgentaLogo className="text-foreground h-6 w-auto" />
+                <p className="text-muted-foreground text-xs">Sign in or create an account.</p>
+            </header>
             <div className="flex w-full max-w-sm flex-col items-center gap-4">{body}</div>
         </div>
     )
diff --git a/web/mobile/src/features/chat/ChatScreen.tsx b/web/mobile/src/features/chat/ChatScreen.tsx
index 2710d1f8bf..20a9b16dd0 100644
--- a/web/mobile/src/features/chat/ChatScreen.tsx
+++ b/web/mobile/src/features/chat/ChatScreen.tsx
@@ -6,6 +6,8 @@ import {
     getPendingApprovals,
 } from "@agenta/chat/model"
 
+import {ScreenScaffold} from "@/components/ScreenScaffold"
+
 import {useLivenessPoll} from "../sessions/useLivenessPoll"
 
 import {ApprovalDock} from "./ApprovalDock"
@@ -76,22 +78,33 @@ export const ChatScreen = ({
     }
 
     return (
-        <div className="bg-background text-foreground flex h-dvh flex-col">
-            <ChatHeader sessionId={sessionId} projectId={projectId} workspaceId={workspaceId} />
-            {running ? (
-                <div className="border-border flex shrink-0 items-center justify-between border-b px-4 py-2">
-                    <span className="text-primary text-xs">A turn is running</span>
-                    <StopButton sessionId={sessionId} projectId={projectId} />
-                </div>
-            ) : null}
-            <div
-                ref={autoScroll.ref}
-                onScroll={autoScroll.onScroll}
-                className="flex flex-1 flex-col overflow-y-auto overscroll-contain"
-            >
-                {body}
-            </div>
-            <ApprovalDock approvals={pendingApprovals} actions={approvals} />
-        </div>
+        <ScreenScaffold
+            scrollRef={autoScroll.ref}
+            onScroll={autoScroll.onScroll}
+            header={
+                <>
+                    <ChatHeader
+                        sessionId={sessionId}
+                        projectId={projectId}
+                        workspaceId={workspaceId}
+                    />
+                    {running ? (
+                        <div className="border-border flex shrink-0 items-center justify-between border-b px-4 py-2">
+                            <span className="text-primary text-xs">A turn is running</span>
+                            <StopButton sessionId={sessionId} projectId={projectId} />
+                        </div>
+                    ) : null}
+                </>
+            }
+            // Only a rendering dock counts as a footer — it owns the safe-area inset, and
+            // ApprovalDock renders nothing when no gate is pending.
+            footer={
+                pendingApprovals.length > 0 ? (
+                    <ApprovalDock approvals={pendingApprovals} actions={approvals} />
+                ) : undefined
+            }
+        >
+            {body}
+        </ScreenScaffold>
     )
 }
diff --git a/web/mobile/src/features/context/ContextResolver.tsx b/web/mobile/src/features/context/ContextResolver.tsx
index 9daa260516..f8cc16bbb4 100644
--- a/web/mobile/src/features/context/ContextResolver.tsx
+++ b/web/mobile/src/features/context/ContextResolver.tsx
@@ -3,26 +3,35 @@ import {useEffect, useMemo, useState} from "react"
 import {useQuery} from "@tanstack/react-query"
 import {useRouter} from "next/router"
 
+import {ScreenScaffold} from "@/components/ScreenScaffold"
 import {fetchProjects, readDesktopLastUsed, readLastContext, type LastContext} from "@/lib/context"
 
+import {selectContextTarget} from "./contextTarget"
 import {SignedOutNotice} from "./states/SignedOutNotice"
 import {WorkspaceProjectList, type WorkspaceGroup} from "./WorkspaceProjectList"
 
 const sessionsUrl = ({workspaceId, projectId}: LastContext) =>
     `/w/${workspaceId}/p/${projectId}/sessions`
 
-/** `/m/` root flow: last-context → auto-forward, else fetch projects and pick. */
+/**
+ * `/m/` root flow: last-context → auto-forward, else fetch projects and pick.
+ *
+ * `?switch=1` suppresses every auto-forward so the picker is reachable from inside the app —
+ * without it a stored context makes this route un-viewable and the workspace unswitchable.
+ */
 export const ContextResolver = () => {
     const router = useRouter()
     // useState initializer: read once, client-only (SSR renders the loading branch).
     const [stored] = useState<LastContext | null>(() =>
         typeof window === "undefined" ? null : readLastContext(),
     )
+    const switching = router.isReady && router.query.switch !== undefined
+    const shortcut = switching ? null : stored
 
     const query = useQuery({
         queryKey: ["mobile", "projects"],
         queryFn: () => fetchProjects(),
-        enabled: !stored,
+        enabled: !shortcut,
         staleTime: 30_000,
     })
     const result = query.data
@@ -43,23 +52,17 @@ export const ContextResolver = () => {
         return [...byWorkspace.values()]
     }, [result])
 
-    const target = useMemo<LastContext | null>(() => {
-        if (stored) return stored
-        if (result?.kind !== "ok" || groups.length === 0) return null
-        if (groups.length === 1 && groups[0].projects.length === 1) {
-            return {workspaceId: groups[0].workspaceId, projectId: groups[0].projects[0].project_id}
-        }
-        // Desktop continuity: forward to the desktop's last-used pair when it
-        // still exists in the fetched tree.
-        const desktopLastUsed = readDesktopLastUsed()
-        for (const group of groups) {
-            const projectId = desktopLastUsed[group.workspaceId]
-            if (projectId && group.projects.some((p) => p.project_id === projectId)) {
-                return {workspaceId: group.workspaceId, projectId}
-            }
-        }
-        return null
-    }, [stored, result, groups])
+    const target = useMemo<LastContext | null>(
+        () =>
+            selectContextTarget({
+                ready: router.isReady,
+                switching,
+                shortcut,
+                groups,
+                desktopLastUsed: readDesktopLastUsed(),
+            }),
+        [router.isReady, switching, shortcut, groups],
+    )
 
     useEffect(() => {
         if (target) void router.replace(sessionsUrl(target))
@@ -67,11 +70,18 @@ export const ContextResolver = () => {
     }, [target])
 
     let body
-    if (target || (!stored && query.isPending)) {
+    // Pinned above the scroller — only the picker branch earns a title.
+    let header
+    if (target || (!shortcut && query.isPending)) {
         body = <p className="text-muted-foreground grow p-6 text-center text-xs">Loading…</p>
     } else if (result?.kind === "unauthenticated") {
         body = <SignedOutNotice />
     } else if (result?.kind === "ok" && groups.length > 0) {
+        header = (
+            <h1 className="border-border shrink-0 border-b p-4 text-xs font-semibold">
+                Choose a project
+            </h1>
+        )
         body = <WorkspaceProjectList groups={groups} />
     } else {
         body = (
@@ -90,19 +100,5 @@ export const ContextResolver = () => {
         )
     }
 
-    return (
-        <div className="bg-background text-foreground flex min-h-dvh flex-col">
-            {body}
-            {/* WP5 gate escape hatch: plain <a> (next/link would prefix /m) to a
-                desktop URL; ?view=desktop sets the agenta-mobile-optout cookie. */}
-            <footer className="pb-[calc(2rem+env(safe-area-inset-bottom))] text-center">
-                <a
-                    href="/w?view=desktop"
-                    className="text-muted-foreground text-xs underline underline-offset-4"
-                >
-                    View desktop site
-                </a>
-            </footer>
-        </div>
-    )
+    return <ScreenScaffold header={header}>{body}</ScreenScaffold>
 }
diff --git a/web/mobile/src/features/context/ProjectSwitcher.tsx b/web/mobile/src/features/context/ProjectSwitcher.tsx
new file mode 100644
index 0000000000..e30d2c484e
--- /dev/null
+++ b/web/mobile/src/features/context/ProjectSwitcher.tsx
@@ -0,0 +1,46 @@
+import {useQuery} from "@tanstack/react-query"
+import {ChevronsUpDown} from "lucide-react"
+import Link from "next/link"
+
+import {fetchProjects} from "@/lib/context"
+
+/**
+ * Where you are, and the way out: workspace / project for the current route, tapping through to
+ * the root picker with `?switch=1` (which suppresses its auto-forward).
+ *
+ * Shares the root picker's query key and staleTime, so arriving here after the picker costs no
+ * request. Names are best-effort — the control still routes to the picker while they resolve.
+ */
+export const ProjectSwitcher = ({
+    workspaceId,
+    projectId,
+}: {
+    workspaceId: string
+    projectId: string
+}) => {
+    const query = useQuery({
+        queryKey: ["mobile", "projects"],
+        queryFn: () => fetchProjects(),
+        staleTime: 30_000,
+    })
+
+    const current =
+        query.data?.kind === "ok"
+            ? query.data.projects.find(
+                  (p) => p.project_id === projectId && p.workspace_id === workspaceId,
+              )
+            : undefined
+
+    return (
+        <Link
+            href="/?switch=1"
+            className="text-muted-foreground -m-1 flex min-h-11 items-center gap-1.5 p-1 text-xs"
+        >
+            <span className="truncate">
+                {current ? `${current.workspace_name ?? "Workspace"} / ` : ""}
+                <span className="text-foreground">{current?.project_name ?? "Switch project"}</span>
+            </span>
+            <ChevronsUpDown aria-hidden className="size-3.5 shrink-0" />
+        </Link>
+    )
+}
diff --git a/web/mobile/src/features/context/WorkspaceProjectList.tsx b/web/mobile/src/features/context/WorkspaceProjectList.tsx
index ed19115c95..01784bd319 100644
--- a/web/mobile/src/features/context/WorkspaceProjectList.tsx
+++ b/web/mobile/src/features/context/WorkspaceProjectList.tsx
@@ -1,3 +1,6 @@
+import {useState} from "react"
+
+import {Building2} from "lucide-react"
 import {useRouter} from "next/router"
 
 import type {MobileProject} from "@/lib/context"
@@ -8,34 +11,74 @@ export interface WorkspaceGroup {
     projects: MobileProject[]
 }
 
-/** Raw nested picker: workspace headers with tappable project rows. */
+/**
+ * Project picker, scoped to one workspace at a time.
+ *
+ * With several workspaces the row of chips IS the workspace selector; with one there is nothing
+ * to select, so the same line degrades to a label naming the workspace you are in (the default
+ * workspace is called "Default", which reads as a duplicate of a project by that name unless
+ * it is labelled).
+ */
 export const WorkspaceProjectList = ({groups}: {groups: WorkspaceGroup[]}) => {
     const router = useRouter()
+    const [selectedId, setSelectedId] = useState(() => groups[0]?.workspaceId ?? "")
+    // Fall back rather than track `groups` in state: a refetch can drop the selected workspace.
+    const selected = groups.find((group) => group.workspaceId === selectedId) ?? groups[0]
+    if (!selected) return null
+
     return (
-        <div className="flex flex-col gap-5 p-4">
-            <h1 className="text-sm font-semibold">Choose a project</h1>
-            {groups.map((group) => (
-                <section key={group.workspaceId} className="flex flex-col gap-1.5">
-                    <h2 className="text-muted-foreground text-xs">{group.workspaceName}</h2>
-                    {group.projects.map((project) => (
-                        <button
-                            key={project.project_id}
-                            type="button"
-                            className="border-border min-h-11 rounded-md border px-3 py-2.5 text-left text-xs"
-                            onClick={() =>
-                                void router.replace(
-                                    `/w/${group.workspaceId}/p/${project.project_id}/sessions`,
-                                )
-                            }
-                        >
-                            {project.project_name}
-                            {project.is_demo ? (
-                                <span className="text-muted-foreground ml-2">demo</span>
-                            ) : null}
-                        </button>
-                    ))}
-                </section>
-            ))}
+        <div className="flex flex-col gap-4 p-4">
+            {groups.length > 1 ? (
+                <div className="flex flex-col gap-2">
+                    <p className="text-muted-foreground text-xs">Workspace</p>
+                    <div className="-mx-4 flex gap-2 overflow-x-auto px-4 pb-1">
+                        {groups.map((group) => {
+                            const isSelected = group.workspaceId === selected.workspaceId
+                            return (
+                                <button
+                                    key={group.workspaceId}
+                                    type="button"
+                                    aria-pressed={isSelected}
+                                    onClick={() => setSelectedId(group.workspaceId)}
+                                    className={`min-h-11 shrink-0 rounded-md border px-3 text-xs ${
+                                        isSelected
+                                            ? "border-foreground text-foreground"
+                                            : "border-border text-muted-foreground"
+                                    }`}
+                                >
+                                    {group.workspaceName}
+                                </button>
+                            )
+                        })}
+                    </div>
+                </div>
+            ) : (
+                <h2 className="text-muted-foreground flex items-center gap-1.5 text-xs">
+                    <Building2 aria-hidden className="size-3.5 shrink-0" />
+                    <span className="truncate">{selected.workspaceName}</span>
+                    <span className="shrink-0 opacity-70">workspace</span>
+                </h2>
+            )}
+
+            <div className="flex flex-col gap-2">
+                {selected.projects.map((project) => (
+                    <button
+                        key={project.project_id}
+                        type="button"
+                        className="border-border min-h-11 rounded-md border px-3 py-2.5 text-left text-xs"
+                        onClick={() =>
+                            void router.replace(
+                                `/w/${selected.workspaceId}/p/${project.project_id}/sessions`,
+                            )
+                        }
+                    >
+                        {project.project_name}
+                        {project.is_demo ? (
+                            <span className="text-muted-foreground ml-2">demo</span>
+                        ) : null}
+                    </button>
+                ))}
+            </div>
         </div>
     )
 }
diff --git a/web/mobile/src/features/context/contextTarget.ts b/web/mobile/src/features/context/contextTarget.ts
new file mode 100644
index 0000000000..f5d1994729
--- /dev/null
+++ b/web/mobile/src/features/context/contextTarget.ts
@@ -0,0 +1,46 @@
+import type {LastContext} from "@/lib/context"
+
+import type {WorkspaceGroup} from "./WorkspaceProjectList"
+
+export interface ContextTargetInput {
+    /** False until the router has parsed the query string. */
+    ready: boolean
+    /** `?switch=1` — the user asked for the picker, so every shortcut is off. */
+    switching: boolean
+    /** Pair remembered from a previous visit. */
+    shortcut: LastContext | null
+    groups: WorkspaceGroup[]
+    /** Desktop's last-used project per workspace. */
+    desktopLastUsed: Record<string, string>
+}
+
+/**
+ * Which project `/m/` should forward to, or `null` to show the picker.
+ *
+ * Ordering is the whole point: `ready` gates everything because a forward decided before the
+ * query string is parsed would blow straight past `?switch=1`, making the picker unreachable
+ * once any context is stored.
+ */
+export const selectContextTarget = ({
+    ready,
+    switching,
+    shortcut,
+    groups,
+    desktopLastUsed,
+}: ContextTargetInput): LastContext | null => {
+    if (!ready || switching) return null
+    if (shortcut) return shortcut
+    if (groups.length === 0) return null
+    // Nothing to choose between.
+    if (groups.length === 1 && groups[0].projects.length === 1) {
+        return {workspaceId: groups[0].workspaceId, projectId: groups[0].projects[0].project_id}
+    }
+    // Desktop continuity: the desktop's last-used pair, when it still exists in the fetched tree.
+    for (const group of groups) {
+        const projectId = desktopLastUsed[group.workspaceId]
+        if (projectId && group.projects.some((p) => p.project_id === projectId)) {
+            return {workspaceId: group.workspaceId, projectId}
+        }
+    }
+    return null
+}
diff --git a/web/mobile/src/features/context/states/SignedOutNotice.tsx b/web/mobile/src/features/context/states/SignedOutNotice.tsx
index b49c043d55..ff1a826305 100644
--- a/web/mobile/src/features/context/states/SignedOutNotice.tsx
+++ b/web/mobile/src/features/context/states/SignedOutNotice.tsx
@@ -2,12 +2,12 @@ import Link from "next/link"
 
 export const SignedOutNotice = () => (
     <div className="flex grow flex-col items-center justify-center gap-2 p-6 text-center">
-        <p className="text-sm font-medium">You are signed out</p>
+        <p className="text-xs font-medium">Sign in to continue</p>
         <Link href="/auth" className="-m-3 p-3 text-xs underline underline-offset-4">
             Sign in
         </Link>
         <p className="text-muted-foreground text-xs">
-            Or sign in on the desktop app, then reload this page.
+            Already signed in on desktop? Reload this page.
         </p>
     </div>
 )
diff --git a/web/mobile/src/features/sessions/SessionListScreen.tsx b/web/mobile/src/features/sessions/SessionListScreen.tsx
index 9366535619..72f121877d 100644
--- a/web/mobile/src/features/sessions/SessionListScreen.tsx
+++ b/web/mobile/src/features/sessions/SessionListScreen.tsx
@@ -1,7 +1,10 @@
 import {useEffect, useMemo, useState} from "react"
 
+import {ScreenScaffold} from "@/components/ScreenScaffold"
 import {clearLastContext} from "@/lib/context"
 
+import {ProjectSwitcher} from "../context/ProjectSwitcher"
+
 import {classifyPageFailure} from "./pageFailure"
 import {SessionRow} from "./SessionRow"
 import {SessionSearchBar} from "./SessionSearchBar"
@@ -88,22 +91,22 @@ export const SessionListScreen = ({
     }
 
     return (
-        <div className="bg-background text-foreground flex h-dvh flex-col">
-            <div className="border-border flex shrink-0 flex-col gap-2 border-b p-4">
-                <SessionSearchBar value={input} onChange={setInput} />
-                {pendingTotal > 0 ? (
-                    <p className="text-primary text-xs">
-                        {pendingTotal} approval{pendingTotal === 1 ? "" : "s"} pending
-                    </p>
-                ) : null}
-            </div>
-            <div
-                ref={scroll.ref}
-                onScroll={scroll.onScroll}
-                className="flex flex-1 flex-col overflow-y-auto overscroll-contain pb-[env(safe-area-inset-bottom)]"
-            >
-                {body}
-            </div>
-        </div>
+        <ScreenScaffold
+            scrollRef={scroll.ref}
+            onScroll={scroll.onScroll}
+            header={
+                <div className="border-border flex shrink-0 flex-col gap-2 border-b p-4">
+                    <ProjectSwitcher workspaceId={workspaceId} projectId={projectId} />
+                    <SessionSearchBar value={input} onChange={setInput} />
+                    {pendingTotal > 0 ? (
+                        <p className="text-primary text-xs">
+                            {pendingTotal} approval{pendingTotal === 1 ? "" : "s"} pending
+                        </p>
+                    ) : null}
+                </div>
+            }
+        >
+            {body}
+        </ScreenScaffold>
     )
 }
diff --git a/web/mobile/tests/unit/contextTarget.test.ts b/web/mobile/tests/unit/contextTarget.test.ts
new file mode 100644
index 0000000000..4a927584f7
--- /dev/null
+++ b/web/mobile/tests/unit/contextTarget.test.ts
@@ -0,0 +1,100 @@
+import {describe, expect, it} from "vitest"
+
+import {
+    selectContextTarget,
+    type ContextTargetInput,
+} from "../../src/features/context/contextTarget"
+import type {WorkspaceGroup} from "../../src/features/context/WorkspaceProjectList"
+
+const project = (projectId: string, workspaceId: string) =>
+    ({
+        project_id: projectId,
+        project_name: projectId,
+        workspace_id: workspaceId,
+        workspace_name: workspaceId,
+    }) as WorkspaceGroup["projects"][number]
+
+const group = (workspaceId: string, projectIds: string[]): WorkspaceGroup => ({
+    workspaceId,
+    workspaceName: workspaceId,
+    projects: projectIds.map((id) => project(id, workspaceId)),
+})
+
+const input = (overrides: Partial<ContextTargetInput> = {}): ContextTargetInput => ({
+    ready: true,
+    switching: false,
+    shortcut: null,
+    groups: [],
+    desktopLastUsed: {},
+    ...overrides,
+})
+
+describe("selectContextTarget", () => {
+    it("forwards to the remembered pair", () => {
+        const shortcut = {workspaceId: "w1", projectId: "p1"}
+        expect(selectContextTarget(input({shortcut}))).toEqual(shortcut)
+    })
+
+    it("decides nothing until the router is ready", () => {
+        // The guard that keeps `?switch=1` reachable: a forward decided on the first render,
+        // before the query string parses, would skip the switch intent entirely.
+        expect(
+            selectContextTarget(
+                input({ready: false, shortcut: {workspaceId: "w1", projectId: "p1"}}),
+            ),
+        ).toBeNull()
+    })
+
+    it("suppresses the remembered pair while switching", () => {
+        expect(
+            selectContextTarget(
+                input({switching: true, shortcut: {workspaceId: "w1", projectId: "p1"}}),
+            ),
+        ).toBeNull()
+    })
+
+    it("suppresses every other shortcut while switching", () => {
+        expect(
+            selectContextTarget(
+                input({
+                    switching: true,
+                    groups: [group("w1", ["p1"])],
+                    desktopLastUsed: {w1: "p1"},
+                }),
+            ),
+        ).toBeNull()
+    })
+
+    it("forwards when there is exactly one project to choose", () => {
+        expect(selectContextTarget(input({groups: [group("w1", ["p1"])]}))).toEqual({
+            workspaceId: "w1",
+            projectId: "p1",
+        })
+    })
+
+    it("shows the picker when a workspace holds several projects", () => {
+        expect(selectContextTarget(input({groups: [group("w1", ["p1", "p2"])]}))).toBeNull()
+    })
+
+    it("follows the desktop's last-used pair", () => {
+        expect(
+            selectContextTarget(
+                input({groups: [group("w1", ["p1", "p2"])], desktopLastUsed: {w1: "p2"}}),
+            ),
+        ).toEqual({workspaceId: "w1", projectId: "p2"})
+    })
+
+    it("ignores a desktop pair whose project is gone", () => {
+        expect(
+            selectContextTarget(
+                input({groups: [group("w1", ["p1", "p2"])], desktopLastUsed: {w1: "deleted"}}),
+            ),
+        ).toBeNull()
+    })
+
+    it("shows the picker when several workspaces are in play", () => {
+        expect(
+            selectContextTarget(input({groups: [group("w1", ["p1"]), group("w2", ["p2"])]})),
+        ).toBeNull()
+    })
+})

From 34efae6b061f03f8a59ed0a2cb0af7ec72ca85c1 Mon Sep 17 00:00:00 2001
From: Arda Erzin <ardaerzin@gmail.com>
Date: Sun, 2 Aug 2026 22:56:45 +0300
Subject: [PATCH 09/19] docs(mobile): plan the split into a reviewable PR stack
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

123 commits in one PR is not reviewable. Measured against candidate lanes, only
three files are touched by two lanes, and in each the lanes stack in the order the
edits happened — so a chronological path-partitioned replay needs no hunk surgery.
Twelve lanes, with the empty diff against the branch tip as the correctness gate.
---
 .../plans/2026-08-01-pr-stack-split.md        | 114 ++++++++++++++++++
 1 file changed, 114 insertions(+)
 create mode 100644 docs/design/agenta-mobile/plans/2026-08-01-pr-stack-split.md

diff --git a/docs/design/agenta-mobile/plans/2026-08-01-pr-stack-split.md b/docs/design/agenta-mobile/plans/2026-08-01-pr-stack-split.md
new file mode 100644
index 0000000000..5ac19759ca
--- /dev/null
+++ b/docs/design/agenta-mobile/plans/2026-08-01-pr-stack-split.md
@@ -0,0 +1,114 @@
+# Splitting `feat/agenta-mobile-wave-1` into a reviewable PR stack
+
+**Status:** proposed
+**Branch:** `feat/agenta-mobile-wave-1` — 123 commits, 293 files, +28 989 / −391 on `main` (`7c395dbecf`)
+
+One PR of this size is not reviewable. This plan cuts it into **12 stacked PRs**, each a
+single reviewable concern, ordered so every PR's base is the branch directly below it.
+
+## Why the branch splits cleanly
+
+The work is already close to path-partitioned. Measuring every commit's files against
+candidate lanes:
+
+- **Only 3 files are touched by two different lanes**: `api/oss/src/apis/fastapi/sessions/models.py`,
+  `.../sessions/router.py` (session-list lane, then watch lane) and
+  `services/runner/src/engines/sandbox_agent/run-turn.ts` (liveness lane, then config lane).
+  In all three cases the lanes are **chronologically ordered the same way they stack**, so a
+  chronological replay puts the earlier hunks in the lower lane and the later hunks in the
+  upper one. No file needs a hunk-level split.
+- Every other file belongs to exactly one lane.
+- Roughly a dozen commits touch two areas (e.g. an `api` change plus its `web/mobile`
+  consumer). Splitting a *commit* by path is trivial; it is splitting a *file* that hurts,
+  and that case does not arise.
+
+## The stack (bottom → top)
+
+Sizes are added lines, measured per lane.
+
+| # | Branch | Lines | Contents |
+|---|---|---|---|
+| 1 | `feat/api-sessions-list-ordering` | 853 | `/sessions/query` ordered by last activity (`coalesce(updated_at, created_at)`, direction-matched id tiebreak), free-text title search, latest-turn references on rows. Includes the `@agenta/entities` wire schema + fixture, and deletes desktop's now-redundant client-side sort. |
+| 2 | `fix/sessions-liveness-and-locks` | 2 390 | Heartbeat writes the liveness mirror on every beat; stale `alive` lock = handover, not turn takeover; **supersession tombstones** (`displaced ⇒ dead`); orphan sweep's two thresholds (300 s running / 1800 s idle); runner's 30-minute approval park; orphaned-gate settle. Subtle concurrency work — the lane that most deserves its own review. |
+| 3 | `feat/api-sessions-watch-sse` | 1 285 | Per-session watch events on the durable Redis plane + `GET /sessions/streams/watch` (metadata-only SSE, 15 s heartbeats, pinned client reconnect delay). |
+| 4 | `feat/api-interactions-respond-answer` | 562 | Compose the approval answer for the detached `POST /sessions/interactions/{id}/respond` path. |
+| 5 | `feat/effective-turn-config` | 1 059 | Three-tier contract, must stay one PR: SDK stamps `effectiveParameters` on the `/run` wire (session runs only, credential-stripped, 64 KB cap) + hydrates references when the caller sent no config; runner echoes it onto the interaction row; API replays it on respond. |
+| 6 | `feat/agenta-chat-package` | 6 297 | The headless `@agenta/chat` extraction. Biggest lane by far, but ~verbatim copies out of `web/oss` — see "Making lane 6 reviewable". |
+| 7 | `feat/entities-session-wire` | ~307 | `@agenta/entities/session` additions the mobile app and desktop share. |
+| 8 | `fix/desktop-session-convergence` | ~250 | Desktop settles a resumed turn's approval gate on replay, converges an open session through the watch relay, and refreshes before reopening a dead relay. Touches `AgentChatSlice` — small, isolated, high-scrutiny. |
+| 9 | `feat/mobile-device-gate` | ~700 | `@agenta/shared` gate decision core + flag-gated OSS/EE middleware (**default off**) + compose flag + UA-emulation smoke. |
+| 10 | `feat/mobile-app-scaffold` | ~1 400 | The `/m` app skeleton: Next.js Pages Router at `basePath: "/m"`, shadcn + palette token bridge, motion presets, eslint bans, workspace wiring, Dockerfile, compose service, CI typecheck/build, entrypoint. |
+| 11 | `feat/mobile-auth` | ~600 | Session-refresh interceptor at provider scope, sign-in parity (email OTP, social providers, org SSO), mobile-initiated OAuth callback handback. |
+| 12 | `feat/mobile-sessions-and-chat` | ~1 900 | Sessions list + transcript replay, approval dock, stop, steer-lite, markdown rendering, live-relay consumption, and the Wave-0 consolidation commits. Split into 12a (list/transcript) and 12b (chat/approvals) if it reads too large. |
+
+**Lanes 1–5 do not depend on any mobile code.** They are ordinary backend improvements and
+can merge to `main` as soon as they are reviewed, which shrinks the stack from underneath
+and de-risks the rest.
+
+## Making lane 6 reviewable
+
+6 297 lines is too many to read, but almost none of it is new logic — `@agenta/chat` was
+**copy-extracted** from `web/oss/src/components/AgentChatSlice`. The PR body should carry a
+per-file drift table (package copy vs its OSS original) so the reviewer reads only the
+drifted lines. Generate it mechanically with `git diff --no-index` per file pair.
+
+Known drift to classify before opening it: ~57 lines in `transcriptToMessages.ts`, and the
+`sessionMessages.ts` divergences already fixed in Wave 0.
+
+Note for the PR body: `grep "@agenta/chat" web/oss/src` returns **0 hits** — OSS has not
+adopted the package it was extracted from. That re-plumb is deliberately out of scope here
+(it collides with the open frontend queue and the antd→shadcn branch) and is tracked as
+Wave 2 of `docs/design/agenta-sessions-consolidation/plan.md`.
+
+## Mechanic: chronological path-partitioned replay
+
+Not `but absorb`, and not hand-assignment against a live working tree — the root
+`AGENTS.md` documents how both mis-route on a pile this size.
+
+For each lane, in stack order:
+
+1. Branch from the previous lane's tip.
+2. Walk the original 123 commits **in chronological order**. For each commit that touches
+   this lane's paths, `git checkout <commit> -- <that commit's files in this lane>` and
+   commit it with the original message (subject unchanged, so the narrative survives).
+3. A commit spanning two lanes contributes one commit to each — no hunk surgery.
+
+Because the replay is chronological and lanes stack in the same order, the 3 shared files
+accumulate their hunks in the right sequence automatically.
+
+### The golden check
+
+After the top lane is built:
+
+```sh
+git diff <top-lane> feat/agenta-mobile-wave-1   # MUST be empty
+```
+
+An empty diff proves the split preserved the exact final tree — no hunk lost, none
+duplicated. Per-lane, verify the **tree** (`git show <lane>:<file>`), not the diff.
+
+Then per lane, bottom-up, confirm the base diff is exactly that lane's files:
+
+```sh
+git diff --name-only <lane-below>..<lane>
+```
+
+## Risks
+
+- **Intermediate lanes must build.** Every original commit compiled, and the replay
+  preserves their order, so any cut point between them is safe. Cut points must fall
+  *between* original commits, never inside one.
+- **Lane 12's mobile app needs lanes 6, 7, 9, 10 beneath it** to typecheck. That ordering is
+  already the stack order.
+- **GitButler stacks are linear** (root `AGENTS.md`). The dependency graph here fans out —
+  e.g. lane 8 (desktop) and lane 12 (mobile) both depend on lane 3 but not on each other —
+  and that cannot be drawn in the git graph. It does not need to be: put every lane in one
+  linear stack and set each PR's `--base` to the branch below it. GitHub then shows only
+  each lane's own delta.
+- **Take a `but oplog snapshot` first.** Recovery is `but oplog restore`.
+
+## Sequencing suggestion
+
+Open lanes 1–5 first and let them merge on their own cadence; they are self-contained
+backend work with no mobile coupling. Open 6–12 once the shape of 1–5 is settled, so the
+frontend lanes rebase onto a shrinking stack rather than a growing one.

From 21f1502e80d8d668d897847fc90b56737640b042 Mon Sep 17 00:00:00 2001
From: Arda Erzin <ardaerzin@gmail.com>
Date: Mon, 3 Aug 2026 09:37:38 +0300
Subject: [PATCH 10/19] fix(chat): re-sync the replay adapter with the OSS
 original, and render attachments
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The package copy had drifted from the original it was extracted from, in two ways that were
both user-visible on mobile.

Approval resume: no pause folding, no settle pass. A turn that paused for a gate and then
resumed replayed as still parked, so a reload kept the approval dock up on a turn the user
had already answered — worst when the gate was answered on another device, where the durable
log carries no interaction_response at all and the settle pass is the only thing that closes
it. Ported with the original's tool-call dedup and re-raise-under-a-new-id handling.

Attachments: a message that carried files replayed as bare text. Ported the file parts and
their content URL (on @agenta/shared/api rather than the OSS app layer), and taught mobile
to render them — inline for images, a labelled link otherwise.

Seven tests ported from the original alongside the settle logic; removing the settle pass
fails the no-interaction_response case.
---
 .../src/features/chat/AttachmentPart.tsx      |  45 +++
 web/mobile/src/features/chat/TurnRow.tsx      |   6 +-
 .../src/assets/transcriptToMessages.ts        | 119 +++++++-
 .../unit/assets/transcriptToMessages.test.ts  | 259 ++++++++++++++++++
 4 files changed, 413 insertions(+), 16 deletions(-)
 create mode 100644 web/mobile/src/features/chat/AttachmentPart.tsx

diff --git a/web/mobile/src/features/chat/AttachmentPart.tsx b/web/mobile/src/features/chat/AttachmentPart.tsx
new file mode 100644
index 0000000000..2f8a3fe7fe
--- /dev/null
+++ b/web/mobile/src/features/chat/AttachmentPart.tsx
@@ -0,0 +1,45 @@
+import {Paperclip} from "lucide-react"
+
+interface FilePart {
+    url?: string
+    mediaType?: string
+    filename?: string
+}
+
+const isImage = (mediaType?: string) => Boolean(mediaType?.startsWith("image/"))
+
+/**
+ * One attachment on a replayed message. The URL is the durable content endpoint, so it carries
+ * the session cookie — an <img> loads it directly, anything else stays a labelled link rather
+ * than a download this screen cannot preview.
+ */
+export const AttachmentPart = ({part}: {part: FilePart}) => {
+    const {url, mediaType, filename} = part
+    if (!url) return null
+
+    if (isImage(mediaType)) {
+        return (
+            <a href={url} target="_blank" rel="noreferrer" className="block max-w-full">
+                {/* Plain <img>: next/image would need the API host allow-listed and cannot
+                    optimize a cookie-authenticated content endpoint. */}
+                <img
+                    src={url}
+                    alt={filename || "attachment"}
+                    className="border-border max-h-60 w-auto max-w-full rounded-lg border object-contain"
+                />
+            </a>
+        )
+    }
+
+    return (
+        <a
+            href={url}
+            target="_blank"
+            rel="noreferrer"
+            className="border-border text-muted-foreground flex min-h-11 max-w-full items-center gap-2 rounded-lg border px-3 text-xs"
+        >
+            <Paperclip aria-hidden className="size-3.5 shrink-0" />
+            <span className="truncate">{filename || mediaType || "attachment"}</span>
+        </a>
+    )
+}
diff --git a/web/mobile/src/features/chat/TurnRow.tsx b/web/mobile/src/features/chat/TurnRow.tsx
index 6daf7b053a..d1bb625bbe 100644
--- a/web/mobile/src/features/chat/TurnRow.tsx
+++ b/web/mobile/src/features/chat/TurnRow.tsx
@@ -1,9 +1,10 @@
 import {partToolName, rowSummary, type TurnViewModel} from "@agenta/chat/model"
 
 import {AssistantMarkdown} from "./AssistantMarkdown"
+import {AttachmentPart} from "./AttachmentPart"
 import {isLiveTextItem} from "./markdownStream"
 
-/** One transcript turn: markdown assistant text, one-line tool summaries, raw error line. */
+/** One transcript turn: markdown text, attachments, one-line tool summaries, raw error line. */
 export const TurnRow = ({turn}: {turn: TurnViewModel}) => (
     <div className={`flex ${turn.isUser ? "justify-end" : "justify-start"}`}>
         <div
@@ -32,6 +33,9 @@ export const TurnRow = ({turn}: {turn: TurnViewModel}) => (
                             />
                         )
                     }
+                    if (item.part.type === "file") {
+                        return <AttachmentPart key={item.index} part={item.part} />
+                    }
                     if (item.part.type === "reasoning") {
                         return (
                             <details key={item.index} className="max-w-full">
diff --git a/web/packages/agenta-chat/src/assets/transcriptToMessages.ts b/web/packages/agenta-chat/src/assets/transcriptToMessages.ts
index 99d6d349c7..505498e230 100644
--- a/web/packages/agenta-chat/src/assets/transcriptToMessages.ts
+++ b/web/packages/agenta-chat/src/assets/transcriptToMessages.ts
@@ -1,7 +1,16 @@
-// Copied verbatim from web/oss/src/components/AgentChatSlice/assets/transcriptToMessages.ts
-// (2026-07-25); the OSS original remains authoritative for the desktop chat until the re-plumb
-// PR deletes it. Keep byte-parity if either side changes.
+// Copied from web/oss/src/components/AgentChatSlice/assets/transcriptToMessages.ts (2026-07-25);
+// the OSS original remains authoritative for the desktop chat until the re-plumb PR deletes it.
+//
+// Re-synced 2026-08-03 to full parity with the original: the approval-resume handling (pause
+// folding, the resumed settle pass, tool-call dedup, re-raise under a new toolCallId) — without
+// which a resumed turn replays as still parked and the reload keeps the approval dock up — and
+// user-attachment parts + `filename` on file parts, without which a message that carried files
+// replays as bare text.
+//
+// `attachmentContentUrl` is the package's own copy of the original's `attachmentMedia.ts`
+// builder, on `@agenta/shared/api` rather than the OSS app layer.
 import type {SessionRecord} from "@agenta/entities/session"
+import {getAgentaApiUrl} from "@agenta/shared/api"
 import type {UIMessage} from "ai"
 
 /**
@@ -21,6 +30,12 @@ import type {UIMessage} from "ai"
 
 type Part = Record<string, unknown>
 
+/** Content URL for one durable attachment. Mirrors the OSS original's `attachmentMedia.ts`. */
+export function attachmentContentUrl(sessionId: string, attachmentId: string): string {
+    const params = new URLSearchParams({session_id: sessionId})
+    return `${getAgentaApiUrl()}/sessions/attachments/${encodeURIComponent(attachmentId)}/content?${params.toString()}`
+}
+
 // Mirrors services/runner/src/tracing/otel.ts; park sentinels report skipped or unobserved work, not final results.
 export const DEFERRED_NOT_EXECUTED_PREFIX = "DEFERRED_NOT_EXECUTED"
 export const APPROVED_EXECUTION_RESULT_UNKNOWN =
@@ -41,6 +56,11 @@ interface DraftMessage {
     traceId?: string
     /** Token/cost totals from the turn's persisted `usage` event, in the raw stream shape. */
     usage?: {input?: number; output?: number; total?: number; cost?: number}
+    /** The turn's terminal `done` carried `stopReason:"paused"` — it ended mid-approval, not at a
+     *  real boundary. Surfaced on the message so a cold reload's adoption heuristic can compare state. */
+    paused?: boolean
+    /** The turn paused for approval and then RESUMED to completion (a second, non-paused `done`). */
+    resumed?: boolean
 }
 
 interface TranscriptIndex {
@@ -110,6 +130,7 @@ function applyEvent(
     draft: DraftMessage,
     payload: Record<string, unknown>,
     index: TranscriptIndex,
+    sessionId: string,
 ): void {
     const type = payload.type as string | undefined
     const str = (v: unknown): string => (typeof v === "string" ? v : v == null ? "" : String(v))
@@ -117,6 +138,25 @@ function applyEvent(
     switch (type) {
         case "message": {
             draft.parts.push({type: "text", text: str(payload.text)})
+            const attachments = Array.isArray(payload.attachments) ? payload.attachments : []
+            for (const raw of attachments) {
+                if (!raw || typeof raw !== "object") continue
+                const attachment = raw as Record<string, unknown>
+                const attachmentId = str(attachment.attachmentId)
+                if (!attachmentId) continue
+                draft.parts.push({
+                    type: "file",
+                    url: attachmentContentUrl(sessionId, attachmentId),
+                    mediaType: str(attachment.mediaType) || "application/octet-stream",
+                    filename: str(attachment.filename) || undefined,
+                    providerMetadata: {
+                        agenta: {
+                            attachmentId,
+                            size: typeof attachment.size === "number" ? attachment.size : undefined,
+                        },
+                    },
+                })
+            }
             return
         }
         case "message_start": {
@@ -147,6 +187,14 @@ function applyEvent(
         }
         case "tool_call": {
             const toolCallId = str(payload.id)
+            const existing = index.tools.get(toolCallId)
+            if (existing) {
+                // A resume re-emits the approved call with the same toolCallId. Update the existing
+                // part (kept across the pause boundary) in place instead of rendering a duplicate;
+                // its tool_result then settles that one part to a single ✓.
+                if (payload.input !== undefined) existing.input = payload.input
+                return
+            }
             const part: Part = {
                 type: toolPartType(payload.name as string),
                 toolCallId,
@@ -214,18 +262,30 @@ function applyEvent(
             const responsePayload = (payload.payload ?? {}) as Record<string, unknown>
             const responseId = str(payload.id)
             const toolCallId = str(responsePayload.toolCallId)
+            // A cold resume re-raises the approved call under a NEW toolCallId, so the interaction
+            // id (identical on request and response by contract) is the reliable key to the gate.
             const part =
-                (toolCallId ? index.tools.get(toolCallId) : undefined) ??
-                index.approvals.get(responseId)
-            if (
-                !part ||
-                part.state !== "approval-requested" ||
-                typeof responsePayload.approved !== "boolean"
-            ) {
-                return
+                index.approvals.get(responseId) ??
+                (toolCallId ? index.tools.get(toolCallId) : undefined)
+            if (!part || typeof responsePayload.approved !== "boolean") return
+            if (part.state === "approval-requested") {
+                part.state = "approval-responded"
+                part.approval = {id: responseId, approved: responsePayload.approved}
+            }
+            if (!toolCallId || toolCallId === str(part.toolCallId)) return
+            // Re-raised under a new id: point that id at the gated part and fold in the duplicate
+            // it created — an executed result supersedes the approval-responded state.
+            const duplicate = index.tools.get(toolCallId)
+            index.tools.set(toolCallId, part)
+            if (!duplicate || duplicate === part) return
+            const at = draft.parts.indexOf(duplicate)
+            if (at >= 0) draft.parts.splice(at, 1)
+            if (duplicate.input !== undefined) part.input = duplicate.input
+            if (typeof duplicate.state === "string" && duplicate.state.startsWith("output-")) {
+                part.state = duplicate.state
+                if (duplicate.output !== undefined) part.output = duplicate.output
+                if (duplicate.errorText !== undefined) part.errorText = duplicate.errorText
             }
-            part.state = "approval-responded"
-            part.approval = {id: responseId, approved: responsePayload.approved}
             return
         }
         case "file": {
@@ -233,6 +293,7 @@ function applyEvent(
                 type: "file",
                 url: str(payload.url),
                 mediaType: str(payload.mediaType),
+                filename: str(payload.filename) || undefined,
             })
             return
         }
@@ -286,7 +347,23 @@ export function transcriptToMessages(records: SessionRecord[]): UIMessage[] | nu
         // this every turn folds into one assistant bubble; closing the draft here starts a
         // fresh message per turn.
         if (row.session_update === "done" || p.type === "done") {
-            if (current && traceId && !current.traceId) current.traceId = traceId
+            // Last-wins: a paused turn folds into its resume (below), and that turn has two `done`s
+            // with two traceIds — prefer the RESUME trace, where the approved tool actually executed.
+            // A normal turn has a single `done`, so this is unchanged for it.
+            if (current && traceId) current.traceId = traceId
+            if (current && p.stopReason === "paused") {
+                // Paused mid-approval: the resume turn's records (the re-emitted call, its result,
+                // the follow-up text) belong to the SAME assistant turn the user saw live, so keep
+                // the draft OPEN and let them fold into it instead of splitting into a dangling
+                // "awaiting approval" bubble + a resumed bubble. A paused turn blocks the session,
+                // so it's always followed by its own resume or is the last (abandoned) turn. Mark it
+                // paused for the adoption heuristic; the normal `done` below clears it on resume.
+                current.paused = true
+                continue
+            }
+            // A resumed-then-completed turn is no longer paused.
+            if (current?.paused) current.resumed = true
+            if (current) current.paused = false
             current = null
             continue
         }
@@ -296,7 +373,18 @@ export function transcriptToMessages(records: SessionRecord[]): UIMessage[] | nu
             drafts.push(current)
         }
         if (traceId && !current.traceId) current.traceId = traceId
-        applyEvent(current, p, index)
+        applyEvent(current, p, index, row.session_id)
+    }
+
+    // A RESUMED turn's gate was answered by definition — the runner only emits post-pause records
+    // once the user responded (a deny settles its own part via `tool_result denied`). The durable
+    // log doesn't always persist the `interaction_response`, so settle whatever is left awaiting:
+    // otherwise a completed turn replays as still parked and the reload keeps the approval dock up.
+    for (const d of drafts) {
+        if (!d.resumed) continue
+        for (const part of d.parts) {
+            if (part.state === "approval-requested") part.state = "approval-responded"
+        }
     }
 
     const messages = drafts
@@ -308,6 +396,7 @@ export function transcriptToMessages(records: SessionRecord[]): UIMessage[] | nu
             const metadata: Record<string, unknown> = {}
             if (d.traceId) metadata.traceId = d.traceId
             if (d.usage) metadata.usage = d.usage
+            if (d.paused) metadata.paused = true
             return {
                 id: d.id,
                 role: d.role,
diff --git a/web/packages/agenta-chat/tests/unit/assets/transcriptToMessages.test.ts b/web/packages/agenta-chat/tests/unit/assets/transcriptToMessages.test.ts
index 058f4df8d3..15cc881ae4 100644
--- a/web/packages/agenta-chat/tests/unit/assets/transcriptToMessages.test.ts
+++ b/web/packages/agenta-chat/tests/unit/assets/transcriptToMessages.test.ts
@@ -120,3 +120,262 @@ describe("transcriptToMessages", () => {
         expect(messages?.[0].parts[0]).toMatchObject({state: "output-denied"})
     })
 })
+
+const approvalRecords = (): SessionRecord[] => [
+    record("record-call", {
+        type: "tool_call",
+        id: "tool-1",
+        name: "bash",
+        input: {command: "ls"},
+    }),
+    record("record-request", {
+        type: "interaction_request",
+        id: "approval-1",
+        kind: "user_approval",
+        payload: {toolCallId: "tool-1"},
+    }),
+]
+
+/**
+ * Ported from the OSS original (see the copy header): a resumed turn must not replay as still
+ * parked, or a reload keeps the approval dock up on a turn the user already answered.
+ */
+describe("transcriptToMessages approval resume", () => {
+    it("merges a paused turn with its resume into one message and settles the re-emitted call once", () => {
+        // Real cold-replay shape (verified against records): a Write call pauses for approval, the
+        // turn ends stopReason:"paused", then the resume turn RE-EMITS the same call id, settles it,
+        // and finishes. Reload must match the single live turn, not a dangling "awaiting" bubble.
+        const messages = transcriptToMessages([
+            record("r-user", {type: "message", text: "write notes.md"}, "user"),
+            record("r-thought-1", {type: "thought", text: "let me write it"}),
+            record("r-call", {
+                type: "tool_call",
+                id: "tool-1",
+                name: "Write",
+                input: {path: "notes.md"},
+            }),
+            record("r-req", {
+                type: "interaction_request",
+                id: "approval-1",
+                kind: "user_approval",
+                payload: {toolCallId: "tool-1"},
+            }),
+            record("r-done-paused", {
+                type: "done",
+                stopReason: "paused",
+                traceId: "trace-paused",
+            }),
+            // resume turn: re-emits the SAME call id, then settles it and finishes.
+            record("r-call-reemit", {
+                type: "tool_call",
+                id: "tool-1",
+                name: "Write",
+                input: {path: "notes.md"},
+            }),
+            record("r-resp", {
+                type: "interaction_response",
+                id: "approval-1",
+                kind: "user_approval",
+                payload: {toolCallId: "tool-1", approved: true},
+            }),
+            record("r-result", {type: "tool_result", id: "tool-1", output: "written"}),
+            record("r-thought-2", {type: "thought", text: "done"}),
+            record("r-msg", {type: "message", text: "Done!"}),
+            record("r-done", {type: "done", traceId: "trace-resume"}),
+        ])
+
+        expect(messages).not.toBeNull()
+        // user + ONE merged assistant turn, not user + paused bubble + resumed bubble.
+        expect(messages).toHaveLength(2)
+        const assistant = messages![1]
+        expect(assistant.role).toBe("assistant")
+
+        // Exactly one Write tool part, settled to a single output-available — no duplicate.
+        const toolParts = (assistant.parts as unknown as Record<string, unknown>[]).filter(
+            (part) => "toolCallId" in part,
+        )
+        expect(toolParts).toHaveLength(1)
+        expect(toolParts[0]).toMatchObject({toolCallId: "tool-1", state: "output-available"})
+
+        // The resumed-and-completed turn is no longer flagged paused.
+        expect(
+            (assistant as unknown as {metadata?: {paused?: boolean}}).metadata?.paused,
+        ).toBeFalsy()
+
+        // "View full trace" on the merged turn links to the RESUME trace (where the tool ran),
+        // not the paused turn's trace.
+        expect((assistant as unknown as {metadata?: {traceId?: string}}).metadata?.traceId).toBe(
+            "trace-resume",
+        )
+    })
+
+    it("settles a resumed turn's gate even when the log has no interaction_response", () => {
+        // Real shape of an approval answered on ANOTHER device (verified against `records`): the
+        // paused turn carries the request, the resume turn carries only thought/usage/message/done —
+        // no `interaction_response`, no re-emitted call, no `tool_result`. The gate must NOT replay
+        // as pending, or the desktop reload keeps showing "Approval needed to continue".
+        const messages = transcriptToMessages([
+            record("r-user", {type: "message", text: "create hello.md"}, "user"),
+            record("r-call", {
+                type: "tool_call",
+                id: "tool-1",
+                name: "bash",
+                input: {command: "cat > hello.md"},
+            }),
+            record("r-req", {
+                type: "interaction_request",
+                id: "approval-1",
+                kind: "user_approval",
+                payload: {toolCallId: "tool-1"},
+            }),
+            record("r-done-paused", {type: "done", stopReason: "paused"}),
+            record("r-thought", {type: "thought", text: "the user approved it"}),
+            record("r-msg", {type: "message", text: "Created hello.md"}),
+            record("r-done", {type: "done"}),
+        ])
+
+        expect(messages).toHaveLength(2)
+        const assistant = messages![1]
+        const parts = assistant.parts as unknown as Record<string, unknown>[]
+        expect(parts.filter((part) => part.state === "approval-requested")).toEqual([])
+        expect(parts.find((part) => part.toolCallId === "tool-1")).toMatchObject({
+            state: "approval-responded",
+            approval: {id: "approval-1"},
+        })
+        expect(
+            (assistant as unknown as {metadata?: {paused?: boolean}}).metadata?.paused,
+        ).toBeFalsy()
+    })
+
+    it("keeps a still-parked turn's gate pending (no resume records yet)", () => {
+        const messages = transcriptToMessages([
+            record("r-user", {type: "message", text: "create hello.md"}, "user"),
+            ...approvalRecords(),
+            record("r-done-paused", {type: "done", stopReason: "paused"}),
+        ])
+
+        const parts = messages![1].parts as unknown as Record<string, unknown>[]
+        expect(parts.find((part) => part.toolCallId === "tool-1")).toMatchObject({
+            state: "approval-requested",
+        })
+    })
+
+    it("leaves a denied call denied across the pause boundary", () => {
+        const messages = transcriptToMessages([
+            record("r-user", {type: "message", text: "create hello.md"}, "user"),
+            ...approvalRecords(),
+            record("r-done-paused", {type: "done", stopReason: "paused"}),
+            record("r-result-denied", {type: "tool_result", id: "tool-1", denied: true}),
+            record("r-msg", {type: "message", text: "Okay, skipping it."}),
+            record("r-done", {type: "done"}),
+        ])
+
+        const parts = messages![1].parts as unknown as Record<string, unknown>[]
+        expect(parts.find((part) => part.toolCallId === "tool-1")).toMatchObject({
+            state: "output-denied",
+        })
+    })
+})
+
+/**
+ * Cold approval resume: the harness re-raises the approved call under a NEW toolCallId, so the
+ * response's `toolCallId` no longer matches the gated part. Only the interaction id still does.
+ */
+describe("transcriptToMessages cold approval resume (re-raised tool call id)", () => {
+    const pausedTurn = (): SessionRecord[] => [
+        record("r-user", {type: "message", text: "delete the file"}, "user"),
+        record("r-call-old", {
+            type: "tool_call",
+            id: "tool-old",
+            name: "bash",
+            input: {command: "rm x"},
+        }),
+        record("r-req", {
+            type: "interaction_request",
+            id: "approval-1",
+            kind: "user_approval",
+            payload: {toolCallId: "tool-old"},
+        }),
+        record("r-done-paused", {type: "done", stopReason: "paused"}),
+        record("r-call-new", {
+            type: "tool_call",
+            id: "tool-new",
+            name: "bash",
+            input: {command: "rm x"},
+        }),
+    ]
+
+    const response = (approved: boolean): SessionRecord =>
+        record("r-resp", {
+            type: "interaction_response",
+            id: "approval-1",
+            kind: "user_approval",
+            payload: {toolCallId: "tool-new", approved},
+        })
+
+    const errorResult = (): SessionRecord =>
+        record("r-result", {
+            type: "tool_result",
+            id: "tool-new",
+            output: "boom",
+            isError: true,
+        })
+
+    const toolParts = (records: SessionRecord[]): Record<string, unknown>[] => {
+        const messages = transcriptToMessages(records)
+        expect(messages).not.toBeNull()
+        return (messages ?? [])
+            .flatMap((message) => message.parts as unknown as Record<string, unknown>[])
+            .filter((part) => "toolCallId" in part)
+    }
+
+    it("settles the gated part when the response arrives before the re-raised result", () => {
+        const parts = toolParts([
+            ...pausedTurn(),
+            response(true),
+            errorResult(),
+            record("r-done", {type: "done"}),
+        ])
+
+        expect(parts).toHaveLength(1)
+        expect(parts[0]).toMatchObject({
+            state: "output-error",
+            errorText: "boom",
+            approval: {id: "approval-1", approved: true},
+        })
+        expect(parts.filter((part) => part.state === "approval-requested")).toEqual([])
+    })
+
+    it("settles the gated part when the re-raised result arrives before the response", () => {
+        const parts = toolParts([
+            ...pausedTurn(),
+            errorResult(),
+            response(true),
+            record("r-done", {type: "done"}),
+        ])
+
+        expect(parts).toHaveLength(1)
+        expect(parts[0]).toMatchObject({
+            state: "output-error",
+            errorText: "boom",
+            approval: {id: "approval-1", approved: true},
+        })
+        expect(parts.filter((part) => part.state === "approval-requested")).toEqual([])
+    })
+
+    it("resolves a denied re-raised call to output-denied", () => {
+        const parts = toolParts([
+            ...pausedTurn(),
+            response(false),
+            record("r-result", {type: "tool_result", id: "tool-new", denied: true}),
+            record("r-done", {type: "done"}),
+        ])
+
+        expect(parts).toHaveLength(1)
+        expect(parts[0]).toMatchObject({
+            state: "output-denied",
+            approval: {id: "approval-1", approved: false},
+        })
+        expect(parts.filter((part) => part.state === "approval-requested")).toEqual([])
+    })
+})

From af8c524c47bbd92edb1edb9f43dbdec00ac91b46 Mon Sep 17 00:00:00 2001
From: Arda Erzin <ardaerzin@gmail.com>
Date: Mon, 3 Aug 2026 09:37:38 +0300
Subject: [PATCH 11/19] docs(mobile): correct the PR-split plan to the mechanic
 actually used
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Path-partitioned replay was rejected during execution: a pre-flight check over the real
commit x file matrix found 42 files touched by more than one lane, 22 with an edit order no
lane ordering can respect — each of which would have had a lower lane replay a newer version
underneath a higher one, silently dropping edits.

Contiguous ranges of the linear history cannot have that failure, and need no replay at all.
Records the 12 lanes as built, and that fixed merge order is the trade.
---
 .../plans/2026-08-01-pr-stack-split.md        | 165 ++++++++----------
 1 file changed, 75 insertions(+), 90 deletions(-)

diff --git a/docs/design/agenta-mobile/plans/2026-08-01-pr-stack-split.md b/docs/design/agenta-mobile/plans/2026-08-01-pr-stack-split.md
index 5ac19759ca..8b38a29ba2 100644
--- a/docs/design/agenta-mobile/plans/2026-08-01-pr-stack-split.md
+++ b/docs/design/agenta-mobile/plans/2026-08-01-pr-stack-split.md
@@ -1,114 +1,99 @@
 # Splitting `feat/agenta-mobile-wave-1` into a reviewable PR stack
 
-**Status:** proposed
-**Branch:** `feat/agenta-mobile-wave-1` — 123 commits, 293 files, +28 989 / −391 on `main` (`7c395dbecf`)
+**Status:** built locally 2026-08-03, unpushed
+**Branch:** `feat/agenta-mobile-wave-1` — 127 commits on `main` (`ac6b1548d9`, = `v0.107.0`)
 
 One PR of this size is not reviewable. This plan cuts it into **12 stacked PRs**, each a
 single reviewable concern, ordered so every PR's base is the branch directly below it.
 
-## Why the branch splits cleanly
+## Why path-partitioning was rejected
 
-The work is already close to path-partitioned. Measuring every commit's files against
-candidate lanes:
+The first version of this plan proposed partitioning by **path** and replaying
+chronologically, on the belief that only 3 files were touched by two lanes. That estimate was
+made against a coarse lane sketch and did not survive the real assignment. A pre-flight check
+over the actual commit×file matrix found **42 files touched by more than one lane, 22 of them
+with an edit order no lane ordering can respect**:
 
-- **Only 3 files are touched by two different lanes**: `api/oss/src/apis/fastapi/sessions/models.py`,
-  `.../sessions/router.py` (session-list lane, then watch lane) and
-  `services/runner/src/engines/sandbox_agent/run-turn.ts` (liveness lane, then config lane).
-  In all three cases the lanes are **chronologically ordered the same way they stack**, so a
-  chronological replay puts the earlier hunks in the lower lane and the later hunks in the
-  upper one. No file needs a hunk-level split.
-- Every other file belongs to exactly one lane.
-- Roughly a dozen commits touch two areas (e.g. an `api` change plus its `web/mobile`
-  consumer). Splitting a *commit* by path is trivial; it is splitting a *file* that hurts,
-  and that case does not arise.
+- `web/turbo.json`, `web/pnpm-lock.yaml` and the dev compose files ping-pong between the
+  mobile-scaffold and device-gate lanes (commits 2 → 42 → 48 → 50 → 53).
+- `api/oss/src/apis/fastapi/sessions/router.py` is touched by the list lane, then the respond
+  lane, then the watch lane — an order those lanes cannot stack in.
+- `web/packages/agenta-shared/src/utils/mobileGate/index.ts` is gate → auth → gate.
 
-## The stack (bottom → top)
-
-Sizes are added lines, measured per lane.
-
-| # | Branch | Lines | Contents |
-|---|---|---|---|
-| 1 | `feat/api-sessions-list-ordering` | 853 | `/sessions/query` ordered by last activity (`coalesce(updated_at, created_at)`, direction-matched id tiebreak), free-text title search, latest-turn references on rows. Includes the `@agenta/entities` wire schema + fixture, and deletes desktop's now-redundant client-side sort. |
-| 2 | `fix/sessions-liveness-and-locks` | 2 390 | Heartbeat writes the liveness mirror on every beat; stale `alive` lock = handover, not turn takeover; **supersession tombstones** (`displaced ⇒ dead`); orphan sweep's two thresholds (300 s running / 1800 s idle); runner's 30-minute approval park; orphaned-gate settle. Subtle concurrency work — the lane that most deserves its own review. |
-| 3 | `feat/api-sessions-watch-sse` | 1 285 | Per-session watch events on the durable Redis plane + `GET /sessions/streams/watch` (metadata-only SSE, 15 s heartbeats, pinned client reconnect delay). |
-| 4 | `feat/api-interactions-respond-answer` | 562 | Compose the approval answer for the detached `POST /sessions/interactions/{id}/respond` path. |
-| 5 | `feat/effective-turn-config` | 1 059 | Three-tier contract, must stay one PR: SDK stamps `effectiveParameters` on the `/run` wire (session runs only, credential-stripped, 64 KB cap) + hydrates references when the caller sent no config; runner echoes it onto the interaction row; API replays it on respond. |
-| 6 | `feat/agenta-chat-package` | 6 297 | The headless `@agenta/chat` extraction. Biggest lane by far, but ~verbatim copies out of `web/oss` — see "Making lane 6 reviewable". |
-| 7 | `feat/entities-session-wire` | ~307 | `@agenta/entities/session` additions the mobile app and desktop share. |
-| 8 | `fix/desktop-session-convergence` | ~250 | Desktop settles a resumed turn's approval gate on replay, converges an open session through the watch relay, and refreshes before reopening a dead relay. Touches `AgentChatSlice` — small, isolated, high-scrutiny. |
-| 9 | `feat/mobile-device-gate` | ~700 | `@agenta/shared` gate decision core + flag-gated OSS/EE middleware (**default off**) + compose flag + UA-emulation smoke. |
-| 10 | `feat/mobile-app-scaffold` | ~1 400 | The `/m` app skeleton: Next.js Pages Router at `basePath: "/m"`, shadcn + palette token bridge, motion presets, eslint bans, workspace wiring, Dockerfile, compose service, CI typecheck/build, entrypoint. |
-| 11 | `feat/mobile-auth` | ~600 | Session-refresh interceptor at provider scope, sign-in parity (email OTP, social providers, org SSO), mobile-initiated OAuth callback handback. |
-| 12 | `feat/mobile-sessions-and-chat` | ~1 900 | Sessions list + transcript replay, approval dock, stop, steer-lite, markdown rendering, live-relay consumption, and the Wave-0 consolidation commits. Split into 12a (list/transcript) and 12b (chat/approvals) if it reads too large. |
-
-**Lanes 1–5 do not depend on any mobile code.** They are ordinary backend improvements and
-can merge to `main` as soon as they are reviewed, which shrinks the stack from underneath
-and de-risks the rest.
-
-## Making lane 6 reviewable
-
-6 297 lines is too many to read, but almost none of it is new logic — `@agenta/chat` was
-**copy-extracted** from `web/oss/src/components/AgentChatSlice`. The PR body should carry a
-per-file drift table (package copy vs its OSS original) so the reviewer reads only the
-drifted lines. Generate it mechanically with `git diff --no-index` per file pair.
-
-Known drift to classify before opening it: ~57 lines in `transcriptToMessages.ts`, and the
-`sessionMessages.ts` divergences already fixed in Wave 0.
-
-Note for the PR body: `grep "@agenta/chat" web/oss/src` returns **0 hits** — OSS has not
-adopted the package it was extracted from. That re-plumb is deliberately out of scope here
-(it collides with the open frontend queue and the antd→shadcn branch) and is tracked as
-Wave 2 of `docs/design/agenta-sessions-consolidation/plan.md`.
+In each case a **lower** lane would replay a **newer** version of the file underneath a higher
+lane, and the higher lane's older content would win — silently dropping edits. The failure is
+invisible in a per-lane diff and only shows up as a wrong final tree.
 
-## Mechanic: chronological path-partitioned replay
+## The mechanic: contiguous ranges of the existing history
 
-Not `but absorb`, and not hand-assignment against a live working tree — the root
-`AGENTS.md` documents how both mis-route on a pile this size.
+Lanes are contiguous spans of the branch's linear history. Every file's edits then appear in
+lane order automatically, so the class of bug above cannot occur.
 
-For each lane, in stack order:
+It also needs **no replay**: each lane is a branch ref at a boundary commit of the history that
+was already reviewed and tested, so the stack is bit-identical to the branch rather than a
+reconstruction of it. `git branch -f <lane> <sha>` per boundary; nothing is rewritten.
 
-1. Branch from the previous lane's tip.
-2. Walk the original 123 commits **in chronological order**. For each commit that touches
-   this lane's paths, `git checkout <commit> -- <that commit's files in this lane>` and
-   commit it with the original message (subject unchanged, so the narrative survives).
-3. A commit spanning two lanes contributes one commit to each — no hunk surgery.
+The cost is that lanes follow *when* work happened rather than *which tier* it touched, so a
+few mix tiers (the approvals lane carries the runner's warm-park change alongside mobile UI).
+The history is already grouped by theme, so in practice each span is coherent.
 
-Because the replay is chronological and lanes stack in the same order, the 3 shared files
-accumulate their hunks in the right sequence automatically.
+Verification is the chain, not a golden diff (which contiguity satisfies trivially): each
+lane's `git merge-base --is-ancestor <below> <lane>` holds, the per-lane commit counts sum to
+the branch total, and the top lane is the same commit as the branch tip.
 
-### The golden check
-
-After the top lane is built:
-
-```sh
-git diff <top-lane> feat/agenta-mobile-wave-1   # MUST be empty
-```
+## The stack (bottom → top)
 
-An empty diff proves the split preserved the exact final tree — no hunk lost, none
-duplicated. Per-lane, verify the **tree** (`git show <lane>:<file>`), not the diff.
+Built 2026-08-03. Each lane's base is the branch directly below it; the bottom lane's base is
+`main`. Commit counts sum to the branch's 127.
+
+| # | Branch | Commits | Files | Contents |
+|---|---|---|---|---|
+| 1 | `feat/mobile-app-scaffold` | 8 | 37 | The `/m` skeleton: Pages Router at `basePath: "/m"`, shadcn + palette token bridge, motion presets, eslint bans (no antd, no app-layer imports), dev compose service behind Traefik. |
+| 2 | `feat/api-sessions-list-ordering` | 9 | 18 | `/sessions/query` ordered by last activity (`coalesce(updated_at, created_at)`, direction-matched id tiebreak), free-text title search, latest-turn references — plus the `@agenta/entities` wire schema and fixture. |
+| 3 | `feat/agenta-chat-package` | 17 | 77 | The headless `@agenta/chat` extraction. Biggest lane; see "Making the chat-package lane reviewable". |
+| 4 | `feat/mobile-image-and-ci` | 5 | 12 | Production gh Dockerfile, typecheck/build workflow, gh compose wiring. |
+| 5 | `feat/mobile-device-gate` | 13 | 28 | Gate decision core in `@agenta/shared`, flag-gated OSS/EE middleware (**default off**), mobile reverse gate, compose flag, UA-emulation smoke. |
+| 6 | `feat/mobile-sessions-and-transcript` | 8 | 34 | `@agenta/*` wired into the app, providers + route-scoped project state, sessions list with search and paging, read-only transcript replay. |
+| 7 | `feat/mobile-auth` | 4 | 10 | Session refresh before the signed-out verdict, raw email sign-in, refresh interceptor at provider scope. |
+| 8 | `feat/mobile-approvals` | 19 | 40 | Approve/deny/stop from the phone, the runner's 30-minute warm park, and the chat UX mechanics (pinned headers, scroll containment, safe-area). |
+| 9 | `feat/sessions-watch-and-liveness` | 16 | 37 | `GET /sessions/streams/watch` SSE relay and its mobile consumer; liveness mirror on every heartbeat, orphan sweep thresholds, handover-vs-takeover, supersession tombstones. |
+| 10 | `feat/effective-turn-config` | 9 | 39 | The three-tier contract: SDK stamps `effectiveParameters` on the `/run` wire, runner echoes it onto the interaction row, API replays it on respond — plus the detached respond dispatcher. |
+| 11 | `fix/desktop-session-convergence` | 7 | 34 | Desktop settles a resumed gate on replay, converges an open session through the watch relay, refreshes before reopening a dead relay; displaced-turn lock closure. |
+| 12 | `feat/mobile-parity-and-consolidation` | 12 | 56 | Steer-lite behind its flag, sign-in parity (OTP/social/SSO) and the OAuth handback, consolidation Wave 0, the approval-envelope `toolName` fix, `@agenta/chat` re-sync. |
+
+Lanes 2, 9, 10 and 11 carry backend work that does not depend on the mobile app. They sit where
+the history put them, but their PRs can be read without reference to the `/m` UI.
+
+## Making the chat-package lane reviewable
+
+Lane 3 is the biggest by far, but almost none of it is new logic — `@agenta/chat` was
+**copy-extracted** from `web/oss/src/components/AgentChatSlice`. The PR body should carry a
+per-file drift table (package copy vs its OSS original) so the reviewer reads only the drifted
+lines. Generate it mechanically with `git diff --no-index` per file pair.
 
-Then per lane, bottom-up, confirm the base diff is exactly that lane's files:
+`transcriptToMessages.ts` was re-synced to full parity on 2026-08-03 (approval-resume handling
+and attachment parts); its copy header records what that covered.
 
-```sh
-git diff --name-only <lane-below>..<lane>
-```
+Note for the PR body: `grep "@agenta/chat" web/oss/src` returns **0 hits** — OSS has not adopted
+the package it was extracted from. That re-plumb is deliberately out of scope (it collides with
+the open frontend queue and the antd→shadcn branch) and is tracked as Wave 2 of
+`docs/design/agenta-sessions-consolidation/plan.md`.
 
 ## Risks
 
-- **Intermediate lanes must build.** Every original commit compiled, and the replay
-  preserves their order, so any cut point between them is safe. Cut points must fall
-  *between* original commits, never inside one.
-- **Lane 12's mobile app needs lanes 6, 7, 9, 10 beneath it** to typecheck. That ordering is
-  already the stack order.
-- **GitButler stacks are linear** (root `AGENTS.md`). The dependency graph here fans out —
-  e.g. lane 8 (desktop) and lane 12 (mobile) both depend on lane 3 but not on each other —
-  and that cannot be drawn in the git graph. It does not need to be: put every lane in one
-  linear stack and set each PR's `--base` to the branch below it. GitHub then shows only
-  each lane's own delta.
-- **Take a `but oplog snapshot` first.** Recovery is `but oplog restore`.
+- **Every lane boundary falls between original commits**, so each lane's tip is a state that was
+  built and tested as part of the branch. No lane is a synthesized tree.
+- **GitButler stacks are linear** (root `AGENTS.md`), which is exactly what this is. Set each
+  PR's `--base` to the branch below it; GitHub then shows only that lane's own delta.
+- **Do not rebase a single lane in isolation.** They share history; rebase the top branch and
+  re-point the boundaries with `git branch -f`, or the chain breaks.
 
 ## Sequencing suggestion
 
-Open lanes 1–5 first and let them merge on their own cadence; they are self-contained
-backend work with no mobile coupling. Open 6–12 once the shape of 1–5 is settled, so the
-frontend lanes rebase onto a shrinking stack rather than a growing one.
+Open the stack bottom-up and let it merge in order. Contiguous lanes cannot be reordered — lane
+N's commits are literally beneath lane N+1 — so the merge order is fixed by construction rather
+than chosen.
+
+That is the trade against the path-partitioned version, which could have let the independent
+backend lanes merge first: here a slow review on lane 1 blocks everything above it. If a lane
+stalls, the escape is to merge it as-is and open a follow-up, not to re-cut the stack.

From c6ee3c34560bd116fb4270b3dadd1951be40de33 Mon Sep 17 00:00:00 2001
From: Arda Erzin <ardaerzin@gmail.com>
Date: Mon, 3 Aug 2026 10:35:02 +0300
Subject: [PATCH 12/19] feat(mobile): poll the session list head so new
 sessions appear
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The list never refreshed. Only staleTime was set, no refetchInterval, and the app disables
refetchOnWindowFocus globally — so a session created on desktop stayed invisible until the
screen remounted. The badges on existing rows polled while the set of rows was frozen.

Poll the newest page as a SEPARATE query rather than adding refetchInterval to the infinite
one: refetching an infinite query refetches every page scrolled into, so its cost grows with
scroll depth. This stays one request per tick. Foreground-only, plus a visibilitychange
refetch so returning from the lock screen does not wait out the interval.

The merge dedupes on session identity and lets the head win on order: a session that just
became active is returned at its new position and would otherwise render twice — fresh at the
top, stale in the page it was fetched in.
---
 .../features/sessions/SessionListScreen.tsx   | 14 ++++-
 .../src/features/sessions/mergeSessionRows.ts | 29 +++++++++
 .../features/sessions/useSessionListHead.ts   | 46 +++++++++++++++
 .../features/sessions/useSessionsInfinite.ts  |  3 +-
 .../tests/unit/mergeSessionRows.test.ts       | 59 +++++++++++++++++++
 5 files changed, 149 insertions(+), 2 deletions(-)
 create mode 100644 web/mobile/src/features/sessions/mergeSessionRows.ts
 create mode 100644 web/mobile/src/features/sessions/useSessionListHead.ts
 create mode 100644 web/mobile/tests/unit/mergeSessionRows.test.ts

diff --git a/web/mobile/src/features/sessions/SessionListScreen.tsx b/web/mobile/src/features/sessions/SessionListScreen.tsx
index 72f121877d..9a4d3b5026 100644
--- a/web/mobile/src/features/sessions/SessionListScreen.tsx
+++ b/web/mobile/src/features/sessions/SessionListScreen.tsx
@@ -5,12 +5,14 @@ import {clearLastContext} from "@/lib/context"
 
 import {ProjectSwitcher} from "../context/ProjectSwitcher"
 
+import {mergeSessionRows} from "./mergeSessionRows"
 import {classifyPageFailure} from "./pageFailure"
 import {SessionRow} from "./SessionRow"
 import {SessionSearchBar} from "./SessionSearchBar"
 import {SessionListEmpty, SessionListError, SessionListLoading} from "./states/SessionListStates"
 import {pendingCountBySession, useActionableInteractions} from "./useActionableInteractions"
 import {livenessBySession, useLivenessPoll} from "./useLivenessPoll"
+import {useSessionListHead} from "./useSessionListHead"
 import {useSessionListScrollRestore} from "./useSessionListScrollRestore"
 import {useSessionsInfinite} from "./useSessionsInfinite"
 
@@ -30,6 +32,9 @@ export const SessionListScreen = ({
     }, [input])
 
     const query = useSessionsInfinite(projectId, search)
+    // Bounded liveness for the list itself: newest page only, so a session created elsewhere
+    // shows up without a manual refresh (see useSessionListHead).
+    const head = useSessionListHead(projectId, search)
     const scroll = useSessionListScrollRestore(projectId, !query.isPending)
     const liveness = useLivenessPoll(projectId)
     const liveBadges = useMemo(() => livenessBySession(liveness.data), [liveness.data])
@@ -49,7 +54,14 @@ export const SessionListScreen = ({
     useEffect(() => {
         if (failed) clearLastContext()
     }, [failed])
-    const rows = pages.flatMap((page) => page ?? []).filter((session) => !session.archived_at)
+    const rows = useMemo(
+        () =>
+            mergeSessionRows(
+                head.data ?? [],
+                (query.data?.pages ?? []).flatMap((page) => page ?? []),
+            ),
+        [head.data, query.data],
+    )
 
     let body
     if (query.isPending) {
diff --git a/web/mobile/src/features/sessions/mergeSessionRows.ts b/web/mobile/src/features/sessions/mergeSessionRows.ts
new file mode 100644
index 0000000000..c658d1170c
--- /dev/null
+++ b/web/mobile/src/features/sessions/mergeSessionRows.ts
@@ -0,0 +1,29 @@
+interface SessionLike {
+    id?: string | null
+    session_id?: string | null
+    archived_at?: string | null
+}
+
+/** A session's stable identity across the two queries; `id` is the paging cursor key. */
+const identity = (session: SessionLike): string => session.session_id || session.id || ""
+
+/**
+ * Merge the polled head (newest page) into the paged rows.
+ *
+ * Head wins on both presence and ORDER: a session that just became active is returned at its new
+ * position by the server, and would otherwise render twice — once fresh at the top, once stale
+ * from the page it was in when that page was fetched. Rows without an identity are dropped; they
+ * cannot be deduped and cannot be linked to.
+ */
+export const mergeSessionRows = <T extends SessionLike>(head: T[], paged: T[]): T[] => {
+    const seen = new Set<string>()
+    const merged: T[] = []
+    for (const session of [...head, ...paged]) {
+        const key = identity(session)
+        if (!key || seen.has(key)) continue
+        if (session.archived_at) continue
+        seen.add(key)
+        merged.push(session)
+    }
+    return merged
+}
diff --git a/web/mobile/src/features/sessions/useSessionListHead.ts b/web/mobile/src/features/sessions/useSessionListHead.ts
new file mode 100644
index 0000000000..4b9c8cf0d0
--- /dev/null
+++ b/web/mobile/src/features/sessions/useSessionListHead.ts
@@ -0,0 +1,46 @@
+import {useEffect} from "react"
+
+import {querySessions} from "@agenta/entities/session"
+import {useQuery} from "@tanstack/react-query"
+
+import {SESSIONS_PAGE_SIZE} from "./useSessionsInfinite"
+
+/**
+ * Poll only the NEWEST page, so a session created elsewhere (desktop, another device, a cron
+ * trigger) appears without a manual refresh.
+ *
+ * Deliberately a separate query rather than a `refetchInterval` on the infinite one: refetching
+ * an infinite query refetches every page scrolled into, so its cost grows with scroll depth.
+ * This is one request per tick no matter how far down the list you are.
+ *
+ * The interval is foreground-only (TanStack's default `refetchIntervalInBackground: false`), and
+ * the visibility listener covers the return itself — the app disables `refetchOnWindowFocus`
+ * globally, so without it a phone coming back from the lock screen waits out the interval.
+ */
+export const useSessionListHead = (projectId: string, search: string) => {
+    const query = useQuery({
+        queryKey: ["mobile", "sessions", "head", projectId, search],
+        enabled: Boolean(projectId),
+        queryFn: ({signal}) =>
+            querySessions({
+                projectId,
+                search: search || undefined,
+                limit: SESSIONS_PAGE_SIZE,
+                includeArchived: false,
+                abortSignal: signal,
+            }),
+        staleTime: 10_000,
+        refetchInterval: 30_000,
+    })
+
+    const {refetch} = query
+    useEffect(() => {
+        const onVisible = () => {
+            if (document.visibilityState === "visible") void refetch()
+        }
+        document.addEventListener("visibilitychange", onVisible)
+        return () => document.removeEventListener("visibilitychange", onVisible)
+    }, [refetch])
+
+    return query
+}
diff --git a/web/mobile/src/features/sessions/useSessionsInfinite.ts b/web/mobile/src/features/sessions/useSessionsInfinite.ts
index d5625d524b..3fb92d93f1 100644
--- a/web/mobile/src/features/sessions/useSessionsInfinite.ts
+++ b/web/mobile/src/features/sessions/useSessionsInfinite.ts
@@ -1,7 +1,8 @@
 import {querySessions} from "@agenta/entities/session"
 import {useInfiniteQuery} from "@tanstack/react-query"
 
-const PAGE_SIZE = 30
+export const SESSIONS_PAGE_SIZE = 30
+const PAGE_SIZE = SESSIONS_PAGE_SIZE
 
 type SessionsCursor = {next: string; newest: string} | null
 
diff --git a/web/mobile/tests/unit/mergeSessionRows.test.ts b/web/mobile/tests/unit/mergeSessionRows.test.ts
new file mode 100644
index 0000000000..b930a15d0c
--- /dev/null
+++ b/web/mobile/tests/unit/mergeSessionRows.test.ts
@@ -0,0 +1,59 @@
+import {describe, expect, it} from "vitest"
+
+import {mergeSessionRows} from "../../src/features/sessions/mergeSessionRows"
+
+const row = (sessionId: string, extra: Record<string, unknown> = {}) => ({
+    id: `row-${sessionId}`,
+    session_id: sessionId,
+    ...extra,
+})
+
+describe("mergeSessionRows", () => {
+    it("returns the paged rows unchanged when the head has nothing new", () => {
+        const paged = [row("a"), row("b")]
+        expect(mergeSessionRows([row("a"), row("b")], paged).map((r) => r.session_id)).toEqual([
+            "a",
+            "b",
+        ])
+    })
+
+    it("surfaces a session the poll found but the pages predate", () => {
+        expect(
+            mergeSessionRows([row("new"), row("a")], [row("a"), row("b")]).map((r) => r.session_id),
+        ).toEqual(["new", "a", "b"])
+    })
+
+    it("keeps a re-activated session once, at its new position", () => {
+        // `b` was fetched deep in a page, then became the most recent — the head returns it at the
+        // top. Without dedupe it renders twice: fresh above, stale below.
+        const merged = mergeSessionRows([row("b")], [row("a"), row("b"), row("c")])
+        expect(merged.map((r) => r.session_id)).toEqual(["b", "a", "c"])
+    })
+
+    it("prefers the head's copy of a row", () => {
+        const merged = mergeSessionRows([row("a", {title: "fresh"})], [row("a", {title: "stale"})])
+        expect(merged).toHaveLength(1)
+        expect((merged[0] as {title?: string}).title).toBe("fresh")
+    })
+
+    it("drops archived rows from either side", () => {
+        const merged = mergeSessionRows(
+            [row("gone", {archived_at: "2026-08-03T00:00:00Z"})],
+            [row("a"), row("also-gone", {archived_at: "2026-08-03T00:00:00Z"})],
+        )
+        expect(merged.map((r) => r.session_id)).toEqual(["a"])
+    })
+
+    it("drops rows with no identity rather than rendering an unlinkable row", () => {
+        const merged = mergeSessionRows([], [{id: null, session_id: null}, row("a")])
+        expect(merged.map((r) => r.session_id)).toEqual(["a"])
+    })
+
+    it("falls back to the row id when session_id is absent", () => {
+        const merged = mergeSessionRows(
+            [{id: "only-row-id", session_id: null}],
+            [{id: "only-row-id", session_id: null}],
+        )
+        expect(merged).toHaveLength(1)
+    })
+})

From 967e79de7a5f4b92368662af2e2d176f0e4bb61e Mon Sep 17 00:00:00 2001
From: Arda Erzin <ardaerzin@gmail.com>
Date: Mon, 3 Aug 2026 10:55:31 +0300
Subject: [PATCH 13/19] feat(mobile): give session and turn statuses a real tag
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Statuses rendered as bare coloured words butted against a title, so "new session test
running" read as a sentence rather than a name plus its state. One StatusTag pill with its
own border and background now carries all of them: the row badges (running/live/approval/
ended), the chat running bar, the transcript's awaiting-approval marker, and the list
header's pending count.

A dot marks the two tones that mean something is happening, so the distinction does not rest
on colour alone. The title truncates independently of its tags, which the old inline spans
could not do — a long name pushed them off the row.
---
 web/mobile/src/components/StatusTag.tsx       | 45 +++++++++++++++++++
 web/mobile/src/features/chat/ChatScreen.tsx   |  5 ++-
 web/mobile/src/features/chat/TurnRow.tsx      |  9 +++-
 .../features/sessions/SessionListScreen.tsx   |  6 ++-
 .../src/features/sessions/SessionRow.tsx      | 26 +++++++----
 5 files changed, 77 insertions(+), 14 deletions(-)
 create mode 100644 web/mobile/src/components/StatusTag.tsx

diff --git a/web/mobile/src/components/StatusTag.tsx b/web/mobile/src/components/StatusTag.tsx
new file mode 100644
index 0000000000..6b8fb0e98c
--- /dev/null
+++ b/web/mobile/src/components/StatusTag.tsx
@@ -0,0 +1,45 @@
+import type {ReactNode} from "react"
+
+import {cn} from "@/lib/utils"
+
+export type StatusTone = "running" | "live" | "attention" | "muted"
+
+const TONES: Record<StatusTone, string> = {
+    // A turn is executing right now — the only tone that earns the accent colour.
+    running: "border-primary/40 text-primary bg-primary/10",
+    // The session is warm but idle: real state, not something to act on.
+    live: "border-border text-muted-foreground bg-muted/40",
+    attention: "border-primary/40 text-primary bg-primary/10",
+    muted: "border-border text-muted-foreground bg-muted/40",
+}
+
+/**
+ * The one status tag across mobile. Statuses used to render as bare coloured words next to a
+ * title, which read as part of the sentence rather than as state — a pill with its own border
+ * and background separates them.
+ *
+ * `dot` is reserved for the two tones that mean "something is happening", so the tag carries the
+ * distinction without relying on colour alone.
+ */
+export const StatusTag = ({
+    tone,
+    dot = false,
+    children,
+    className,
+}: {
+    tone: StatusTone
+    dot?: boolean
+    children: ReactNode
+    className?: string
+}) => (
+    <span
+        className={cn(
+            "inline-flex shrink-0 items-center gap-1 rounded-full border px-2 py-0.5 text-xs leading-none font-medium",
+            TONES[tone],
+            className,
+        )}
+    >
+        {dot ? <span aria-hidden className="size-1.5 rounded-full bg-current" /> : null}
+        {children}
+    </span>
+)
diff --git a/web/mobile/src/features/chat/ChatScreen.tsx b/web/mobile/src/features/chat/ChatScreen.tsx
index 20a9b16dd0..f83236003d 100644
--- a/web/mobile/src/features/chat/ChatScreen.tsx
+++ b/web/mobile/src/features/chat/ChatScreen.tsx
@@ -7,6 +7,7 @@ import {
 } from "@agenta/chat/model"
 
 import {ScreenScaffold} from "@/components/ScreenScaffold"
+import {StatusTag} from "@/components/StatusTag"
 
 import {useLivenessPoll} from "../sessions/useLivenessPoll"
 
@@ -90,7 +91,9 @@ export const ChatScreen = ({
                     />
                     {running ? (
                         <div className="border-border flex shrink-0 items-center justify-between border-b px-4 py-2">
-                            <span className="text-primary text-xs">A turn is running</span>
+                            <StatusTag tone="running" dot>
+                                running
+                            </StatusTag>
                             <StopButton sessionId={sessionId} projectId={projectId} />
                         </div>
                     ) : null}
diff --git a/web/mobile/src/features/chat/TurnRow.tsx b/web/mobile/src/features/chat/TurnRow.tsx
index d1bb625bbe..b72f764657 100644
--- a/web/mobile/src/features/chat/TurnRow.tsx
+++ b/web/mobile/src/features/chat/TurnRow.tsx
@@ -1,5 +1,7 @@
 import {partToolName, rowSummary, type TurnViewModel} from "@agenta/chat/model"
 
+import {StatusTag} from "@/components/StatusTag"
+
 import {AssistantMarkdown} from "./AssistantMarkdown"
 import {AttachmentPart} from "./AttachmentPart"
 import {isLiveTextItem} from "./markdownStream"
@@ -59,8 +61,11 @@ export const TurnRow = ({turn}: {turn: TurnViewModel}) => (
                                     // The decision lives in the bottom ApprovalDock; the row is
                                     // just the marker (desktop parity).
                                     return (
-                                        <p key={key} className="text-muted-foreground text-xs">
-                                            Awaiting approval — {partToolName(part)}
+                                        <p key={key} className="flex items-center gap-2 text-xs">
+                                            <StatusTag tone="attention">approval</StatusTag>
+                                            <span className="text-muted-foreground truncate">
+                                                {partToolName(part)}
+                                            </span>
                                         </p>
                                     )
                                 }
diff --git a/web/mobile/src/features/sessions/SessionListScreen.tsx b/web/mobile/src/features/sessions/SessionListScreen.tsx
index 9a4d3b5026..1d239f1ddd 100644
--- a/web/mobile/src/features/sessions/SessionListScreen.tsx
+++ b/web/mobile/src/features/sessions/SessionListScreen.tsx
@@ -1,6 +1,7 @@
 import {useEffect, useMemo, useState} from "react"
 
 import {ScreenScaffold} from "@/components/ScreenScaffold"
+import {StatusTag} from "@/components/StatusTag"
 import {clearLastContext} from "@/lib/context"
 
 import {ProjectSwitcher} from "../context/ProjectSwitcher"
@@ -111,8 +112,9 @@ export const SessionListScreen = ({
                     <ProjectSwitcher workspaceId={workspaceId} projectId={projectId} />
                     <SessionSearchBar value={input} onChange={setInput} />
                     {pendingTotal > 0 ? (
-                        <p className="text-primary text-xs">
-                            {pendingTotal} approval{pendingTotal === 1 ? "" : "s"} pending
+                        <p className="flex items-center gap-2">
+                            <StatusTag tone="attention">{pendingTotal} pending</StatusTag>
+                            <span className="text-muted-foreground text-xs">waiting on you</span>
                         </p>
                     ) : null}
                 </div>
diff --git a/web/mobile/src/features/sessions/SessionRow.tsx b/web/mobile/src/features/sessions/SessionRow.tsx
index 994a1b4157..482060795b 100644
--- a/web/mobile/src/features/sessions/SessionRow.tsx
+++ b/web/mobile/src/features/sessions/SessionRow.tsx
@@ -1,6 +1,8 @@
 import type {SessionStream} from "@agenta/entities/session"
 import Link from "next/link"
 
+import {StatusTag} from "@/components/StatusTag"
+
 import type {SessionLivenessBadge} from "./useLivenessPoll"
 
 /** Raw relative time ("3h ago") — enough for the LITE phase, no dayjs. */
@@ -37,20 +39,26 @@ export const SessionRow = ({
     // is_running=true for days after a crashed run) — only the live poll may badge.
     const badge = liveness ?? null
     return (
-        <Link href={href} className="border-border flex flex-col gap-0.5 border-b px-4 py-3">
-            <span className="text-xs font-medium">
-                {session.name ?? "Untitled session"}
+        <Link href={href} className="border-border flex flex-col gap-1 border-b px-4 py-3">
+            <span className="flex min-w-0 items-center gap-2">
+                <span className="truncate text-xs font-medium">
+                    {session.name ?? "Untitled session"}
+                </span>
                 {badge === "running" ? (
-                    <span className="text-primary ml-2 font-normal">running</span>
+                    <StatusTag tone="running" dot>
+                        running
+                    </StatusTag>
                 ) : badge === "alive" ? (
-                    <span className="text-muted-foreground ml-2 font-normal">live</span>
+                    <StatusTag tone="live" dot>
+                        live
+                    </StatusTag>
                 ) : null}
                 {pendingApprovals > 0 ? (
-                    <span className="text-primary ml-2 font-normal">needs approval</span>
-                ) : null}
-                {session.deleted_at ? (
-                    <span className="text-muted-foreground ml-2 font-normal">ended</span>
+                    <StatusTag tone="attention">
+                        {pendingApprovals > 1 ? `${pendingApprovals} approvals` : "approval"}
+                    </StatusTag>
                 ) : null}
+                {session.deleted_at ? <StatusTag tone="muted">ended</StatusTag> : null}
             </span>
             <span className="text-muted-foreground text-xs">
                 {agentLabel}

From df9e3eee0272cdbdc699adb9fe61d6d27f6a3525 Mon Sep 17 00:00:00 2001
From: Arda Erzin <ardaerzin@gmail.com>
Date: Mon, 3 Aug 2026 11:10:29 +0300
Subject: [PATCH 14/19] fix(mobile): stop live and ended sessions rendering as
 the same pill
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The live and muted tones had byte-identical class strings, so a warm session and an ended one
differed only by a dot — which is why live read as inert grey. They are opposite states.

Bridge the palette semantic success role into the mobile theme (it already carries error) and
give live its own tone. The three states are now separable without reading the label: accent
means act on this, success means healthy and warm, muted means nothing is happening.
---
 web/mobile/scripts/generate-shadcn-tokens.ts |  3 +++
 web/mobile/src/components/StatusTag.tsx      | 10 +++++++---
 web/mobile/src/styles/globals.css            |  1 +
 web/mobile/src/styles/theme.generated.css    |  2 ++
 4 files changed, 13 insertions(+), 3 deletions(-)

diff --git a/web/mobile/scripts/generate-shadcn-tokens.ts b/web/mobile/scripts/generate-shadcn-tokens.ts
index 28d99e998b..7a610e3e4b 100644
--- a/web/mobile/scripts/generate-shadcn-tokens.ts
+++ b/web/mobile/scripts/generate-shadcn-tokens.ts
@@ -57,6 +57,9 @@ const VARS: Record<string, [string, string]> = {
     accent: [color(p.surface.controlItemBgActive.light), color(p.scales.zinc[2].dark)],
     "accent-foreground": [color(p.text.primary.light), color(p.text.primary.dark)],
     destructive: [color(p.semantic.error.light), color(p.semantic.error.dark)],
+    // Not a shadcn role: session liveness needs a third state between the accent (a turn is
+    // running, act on it) and muted (ended). Same semantic family the desktop uses for "healthy".
+    success: [color(p.semantic.success.light), color(p.semantic.success.dark)],
     // Bright-red fill gets dark text in dark mode, matching the primary treatment.
     "destructive-foreground": [color(p.surface.white.light), p.componentsDark.Button.primaryColor],
     border: [color(p.border.secondary.light), color(p.border.secondary.dark)],
diff --git a/web/mobile/src/components/StatusTag.tsx b/web/mobile/src/components/StatusTag.tsx
index 6b8fb0e98c..31f28d8f3f 100644
--- a/web/mobile/src/components/StatusTag.tsx
+++ b/web/mobile/src/components/StatusTag.tsx
@@ -4,11 +4,15 @@ import {cn} from "@/lib/utils"
 
 export type StatusTone = "running" | "live" | "attention" | "muted"
 
+/**
+ * Three distinct states, distinguishable without reading the label: the accent means "act on
+ * this", success means "healthy and warm", muted means "nothing is happening here". `live` and
+ * `muted` must never collapse to the same treatment — a warm session and an ended one are
+ * opposites, and rendering both as the same grey pill is what made "live" read as inert.
+ */
 const TONES: Record<StatusTone, string> = {
-    // A turn is executing right now — the only tone that earns the accent colour.
     running: "border-primary/40 text-primary bg-primary/10",
-    // The session is warm but idle: real state, not something to act on.
-    live: "border-border text-muted-foreground bg-muted/40",
+    live: "border-success/40 text-success bg-success/10",
     attention: "border-primary/40 text-primary bg-primary/10",
     muted: "border-border text-muted-foreground bg-muted/40",
 }
diff --git a/web/mobile/src/styles/globals.css b/web/mobile/src/styles/globals.css
index d0f91f7688..bd4b0c3861 100644
--- a/web/mobile/src/styles/globals.css
+++ b/web/mobile/src/styles/globals.css
@@ -35,6 +35,7 @@
     --color-accent-foreground: var(--accent-foreground);
     --color-destructive: var(--destructive);
     --color-destructive-foreground: var(--destructive-foreground);
+    --color-success: var(--success);
     --color-border: var(--border);
     --color-input: var(--input);
     --color-ring: var(--ring);
diff --git a/web/mobile/src/styles/theme.generated.css b/web/mobile/src/styles/theme.generated.css
index 5796a316b8..700f8de8a6 100644
--- a/web/mobile/src/styles/theme.generated.css
+++ b/web/mobile/src/styles/theme.generated.css
@@ -18,6 +18,7 @@
     --accent: #f5f7fa;
     --accent-foreground: #1c2c3d;
     --destructive: #d61010;
+    --success: #389e0d;
     --destructive-foreground: #ffffff;
     --border: #eaeff5;
     --input: #bdc7d1;
@@ -40,6 +41,7 @@
     --accent: #2a2a2a;
     --accent-foreground: rgba(255, 255, 255, 0.85);
     --destructive: #ff4d4f;
+    --success: #52c41a;
     --destructive-foreground: #141414;
     --border: #303030;
     --input: #424242;

From 804e82f36247d5411776d1e59ac094a058126876 Mon Sep 17 00:00:00 2001
From: Arda Erzin <ardaerzin@gmail.com>
Date: Mon, 3 Aug 2026 11:15:05 +0300
Subject: [PATCH 15/19] feat(mobile): make the waiting count a filter instead
 of a statistic
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

"2 approvals pending" told you work existed and left you to find it. The count is now a
toggle that narrows the list to the sessions waiting on you.

It counts SESSIONS, not interactions — the filter shows rows, and one session can hold several
gates, so the old number could exceed the rows it produced.

The interactions poll is project-wide while the list is paged, so a waiting session can sit
beyond what has been fetched. Rather than silently showing a short list, the filter reports
how many are further down and offers to load them; the empty case says the same instead of
claiming there is nothing to do. Answering the last gate clears the filter rather than
stranding the user on an empty list.
---
 .../features/sessions/SessionListScreen.tsx   | 60 ++++++++++++++++---
 .../src/features/sessions/pendingFilter.ts    | 38 ++++++++++++
 .../sessions/states/SessionListStates.tsx     | 34 +++++++++++
 web/mobile/tests/unit/pendingFilter.test.ts   | 47 +++++++++++++++
 4 files changed, 170 insertions(+), 9 deletions(-)
 create mode 100644 web/mobile/src/features/sessions/pendingFilter.ts
 create mode 100644 web/mobile/tests/unit/pendingFilter.test.ts

diff --git a/web/mobile/src/features/sessions/SessionListScreen.tsx b/web/mobile/src/features/sessions/SessionListScreen.tsx
index 1d239f1ddd..d26eb81608 100644
--- a/web/mobile/src/features/sessions/SessionListScreen.tsx
+++ b/web/mobile/src/features/sessions/SessionListScreen.tsx
@@ -8,9 +8,15 @@ import {ProjectSwitcher} from "../context/ProjectSwitcher"
 
 import {mergeSessionRows} from "./mergeSessionRows"
 import {classifyPageFailure} from "./pageFailure"
+import {filterPendingRows} from "./pendingFilter"
 import {SessionRow} from "./SessionRow"
 import {SessionSearchBar} from "./SessionSearchBar"
-import {SessionListEmpty, SessionListError, SessionListLoading} from "./states/SessionListStates"
+import {
+    SessionListEmpty,
+    SessionListError,
+    SessionListLoading,
+    SessionListPendingEmpty,
+} from "./states/SessionListStates"
 import {pendingCountBySession, useActionableInteractions} from "./useActionableInteractions"
 import {livenessBySession, useLivenessPoll} from "./useLivenessPoll"
 import {useSessionListHead} from "./useSessionListHead"
@@ -25,6 +31,7 @@ export const SessionListScreen = ({
     workspaceId: string
     projectId: string
 }) => {
+    const [onlyPending, setOnlyPending] = useState(false)
     const [input, setInput] = useState("")
     const [search, setSearch] = useState("")
     useEffect(() => {
@@ -44,7 +51,8 @@ export const SessionListScreen = ({
         () => pendingCountBySession(interactions.data),
         [interactions.data],
     )
-    const pendingTotal = interactions.data?.length ?? 0
+    // Sessions, not interactions: the filter shows rows, and one session can hold several gates.
+    const waitingSessions = pendingBySession?.size ?? 0
     const pages = query.data?.pages ?? []
     const {failed, laterPageFailed} = classifyPageFailure(pages, query.isError)
 
@@ -55,7 +63,7 @@ export const SessionListScreen = ({
     useEffect(() => {
         if (failed) clearLastContext()
     }, [failed])
-    const rows = useMemo(
+    const merged = useMemo(
         () =>
             mergeSessionRows(
                 head.data ?? [],
@@ -63,6 +71,16 @@ export const SessionListScreen = ({
             ),
         [head.data, query.data],
     )
+    const pending = useMemo(
+        () => filterPendingRows(merged, pendingBySession),
+        [merged, pendingBySession],
+    )
+    const rows = onlyPending ? pending.rows : merged
+
+    // Answering the last gate must not strand the user on an empty filtered list.
+    useEffect(() => {
+        if (onlyPending && waitingSessions === 0) setOnlyPending(false)
+    }, [onlyPending, waitingSessions])
 
     let body
     if (query.isPending) {
@@ -70,10 +88,27 @@ export const SessionListScreen = ({
     } else if (failed) {
         body = <SessionListError onRetry={() => void query.refetch()} />
     } else if (rows.length === 0) {
-        body = <SessionListEmpty />
+        // Filtered-empty is not the same as project-empty: the waiting sessions are real, just
+        // deeper than the pages fetched so far.
+        body = onlyPending ? (
+            <SessionListPendingEmpty
+                unloaded={pending.unloaded}
+                canLoadMore={Boolean(query.hasNextPage)}
+                loading={query.isFetchingNextPage}
+                onLoadMore={() => void query.fetchNextPage()}
+            />
+        ) : (
+            <SessionListEmpty />
+        )
     } else {
         body = (
             <div className="flex flex-col">
+                {onlyPending && pending.unloaded > 0 ? (
+                    <p className="text-muted-foreground border-border border-b px-4 py-2 text-xs">
+                        {pending.unloaded} more waiting further down the list — load more to reach{" "}
+                        {pending.unloaded === 1 ? "it" : "them"}.
+                    </p>
+                ) : null}
                 {rows.map((session) => (
                     <SessionRow
                         key={session.id}
@@ -111,11 +146,18 @@ export const SessionListScreen = ({
                 <div className="border-border flex shrink-0 flex-col gap-2 border-b p-4">
                     <ProjectSwitcher workspaceId={workspaceId} projectId={projectId} />
                     <SessionSearchBar value={input} onChange={setInput} />
-                    {pendingTotal > 0 ? (
-                        <p className="flex items-center gap-2">
-                            <StatusTag tone="attention">{pendingTotal} pending</StatusTag>
-                            <span className="text-muted-foreground text-xs">waiting on you</span>
-                        </p>
+                    {waitingSessions > 0 ? (
+                        <button
+                            type="button"
+                            aria-pressed={onlyPending}
+                            onClick={() => setOnlyPending((on) => !on)}
+                            className="-m-1 flex min-h-11 items-center gap-2 p-1 text-left"
+                        >
+                            <StatusTag tone="attention">{waitingSessions} waiting</StatusTag>
+                            <span className="text-muted-foreground text-xs underline underline-offset-4">
+                                {onlyPending ? "show all sessions" : "show only these"}
+                            </span>
+                        </button>
                     ) : null}
                 </div>
             }
diff --git a/web/mobile/src/features/sessions/pendingFilter.ts b/web/mobile/src/features/sessions/pendingFilter.ts
new file mode 100644
index 0000000000..ac5115d8a5
--- /dev/null
+++ b/web/mobile/src/features/sessions/pendingFilter.ts
@@ -0,0 +1,38 @@
+interface RowLike {
+    session_id?: string | null
+}
+
+export interface PendingFilter<T> {
+    rows: T[]
+    /** Sessions with a pending gate that the loaded pages do not contain yet. */
+    unloaded: number
+}
+
+/**
+ * Narrow the list to sessions waiting on a human.
+ *
+ * The interactions poll is project-wide but the list is paged, so a waiting session can exist
+ * beyond what has been fetched. Report that count rather than silently showing a short list —
+ * "2 waiting" next to one row is a bug the user cannot explain.
+ */
+export const filterPendingRows = <T extends RowLike>(
+    rows: T[],
+    pendingBySession: Map<string, number> | undefined,
+): PendingFilter<T> => {
+    if (!pendingBySession) return {rows, unloaded: 0}
+
+    const loaded = new Set<string>()
+    for (const row of rows) if (row.session_id) loaded.add(row.session_id)
+
+    let unloaded = 0
+    for (const sessionId of pendingBySession.keys()) {
+        if (!loaded.has(sessionId)) unloaded += 1
+    }
+
+    return {
+        rows: rows.filter(
+            (row) => (row.session_id ? (pendingBySession.get(row.session_id) ?? 0) : 0) > 0,
+        ),
+        unloaded,
+    }
+}
diff --git a/web/mobile/src/features/sessions/states/SessionListStates.tsx b/web/mobile/src/features/sessions/states/SessionListStates.tsx
index 22a3067c4f..582ad3ba39 100644
--- a/web/mobile/src/features/sessions/states/SessionListStates.tsx
+++ b/web/mobile/src/features/sessions/states/SessionListStates.tsx
@@ -9,6 +9,40 @@ export const SessionListEmpty = () => (
     <p className="text-muted-foreground grow p-6 text-center text-xs">No sessions.</p>
 )
 
+/**
+ * The waiting filter matched nothing in the loaded pages. `unloaded` sessions are waiting further
+ * down, so this offers the way to reach them instead of claiming there is nothing to do.
+ */
+export const SessionListPendingEmpty = ({
+    unloaded,
+    canLoadMore,
+    loading,
+    onLoadMore,
+}: {
+    unloaded: number
+    canLoadMore: boolean
+    loading: boolean
+    onLoadMore: () => void
+}) => (
+    <div className="flex grow flex-col items-center justify-center gap-3 p-6 text-center">
+        <p className="text-muted-foreground text-xs">
+            {unloaded > 0
+                ? `${unloaded} session${unloaded === 1 ? "" : "s"} waiting further down the list.`
+                : "Nothing waiting on you."}
+        </p>
+        {unloaded > 0 && canLoadMore ? (
+            <button
+                type="button"
+                className="border-border min-h-11 rounded-md border px-3 py-2 text-xs"
+                disabled={loading}
+                onClick={onLoadMore}
+            >
+                {loading ? "Loading…" : "Load more"}
+            </button>
+        ) : null}
+    </div>
+)
+
 export const SessionListError = ({onRetry}: {onRetry: () => void}) => (
     <div className="flex grow flex-col items-center justify-center gap-3 p-6 text-center">
         <p className="text-muted-foreground text-xs">Something went wrong.</p>
diff --git a/web/mobile/tests/unit/pendingFilter.test.ts b/web/mobile/tests/unit/pendingFilter.test.ts
new file mode 100644
index 0000000000..baf2a80253
--- /dev/null
+++ b/web/mobile/tests/unit/pendingFilter.test.ts
@@ -0,0 +1,47 @@
+import {describe, expect, it} from "vitest"
+
+import {filterPendingRows} from "../../src/features/sessions/pendingFilter"
+
+const row = (sessionId: string) => ({id: `row-${sessionId}`, session_id: sessionId})
+
+describe("filterPendingRows", () => {
+    it("keeps only the sessions with a pending gate", () => {
+        const result = filterPendingRows([row("a"), row("b"), row("c")], new Map([["b", 1]]))
+        expect(result.rows.map((r) => r.session_id)).toEqual(["b"])
+        expect(result.unloaded).toBe(0)
+    })
+
+    it("counts waiting sessions the loaded pages do not contain", () => {
+        // The interactions poll is project-wide; this one lives beyond the fetched pages.
+        const result = filterPendingRows(
+            [row("a")],
+            new Map([
+                ["a", 1],
+                ["deep-in-page-4", 2],
+            ]),
+        )
+        expect(result.rows.map((r) => r.session_id)).toEqual(["a"])
+        expect(result.unloaded).toBe(1)
+    })
+
+    it("passes rows through untouched while the poll is unresolved", () => {
+        const rows = [row("a"), row("b")]
+        const result = filterPendingRows(rows, undefined)
+        expect(result.rows).toBe(rows)
+        expect(result.unloaded).toBe(0)
+    })
+
+    it("returns nothing when no session is waiting", () => {
+        const result = filterPendingRows([row("a")], new Map())
+        expect(result.rows).toEqual([])
+        expect(result.unloaded).toBe(0)
+    })
+
+    it("ignores rows with no session id", () => {
+        const result = filterPendingRows(
+            [{id: "x", session_id: null}, row("a")],
+            new Map([["a", 1]]),
+        )
+        expect(result.rows.map((r) => r.session_id)).toEqual(["a"])
+    })
+})

From ce9b8b0e90e761908794e81f01e6df0c039a0774 Mon Sep 17 00:00:00 2001
From: Arda Erzin <ardaerzin@gmail.com>
Date: Mon, 3 Aug 2026 11:18:05 +0300
Subject: [PATCH 16/19] fix(mobile): make the waiting filter one chip instead
 of a dangling phrase
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

"show only these" pointed at nothing — while the filter is off the rows it means are not on
screen, and a pill next to an underlined phrase reads as two controls when it is one.

One toggleable chip carries it: the icon supplies the affordance (funnel to apply, cross to
clear) so the visible label stays the count, and the spoken label is the full sentence the
visible text should not have to be. The unloaded-count copy loses its instruction too — the
Load more button is directly beneath it.
---
 web/mobile/src/components/FilterChip.tsx      | 46 +++++++++++++++++++
 .../features/sessions/SessionListScreen.tsx   | 25 +++++-----
 .../sessions/states/SessionListStates.tsx     |  2 +-
 3 files changed, 59 insertions(+), 14 deletions(-)
 create mode 100644 web/mobile/src/components/FilterChip.tsx

diff --git a/web/mobile/src/components/FilterChip.tsx b/web/mobile/src/components/FilterChip.tsx
new file mode 100644
index 0000000000..2a0ecb81d7
--- /dev/null
+++ b/web/mobile/src/components/FilterChip.tsx
@@ -0,0 +1,46 @@
+import type {ReactNode} from "react"
+
+import {ListFilter, X} from "lucide-react"
+
+import {cn} from "@/lib/utils"
+
+/**
+ * A toggleable filter, styled as one chip rather than a label plus a verb phrase — a separate
+ * "show only these" link reads as a second control, and its demonstrative has no antecedent
+ * while the filter is off and the rows are not on screen yet.
+ *
+ * The icon carries the affordance (funnel to apply, cross to clear) so the label can stay the
+ * plain count it filters by.
+ */
+export const FilterChip = ({
+    active,
+    onToggle,
+    label,
+    children,
+}: {
+    active: boolean
+    onToggle: () => void
+    /** Spoken label — the visible text is only a count, which says nothing on its own. */
+    label: string
+    children: ReactNode
+}) => (
+    <button
+        type="button"
+        aria-pressed={active}
+        aria-label={label}
+        onClick={onToggle}
+        className={cn(
+            "inline-flex min-h-11 shrink-0 items-center gap-1.5 self-start rounded-full border px-3 text-xs font-medium",
+            active
+                ? "border-primary bg-primary text-primary-foreground"
+                : "border-primary/40 text-primary bg-primary/10",
+        )}
+    >
+        {active ? (
+            <X aria-hidden className="size-3.5" />
+        ) : (
+            <ListFilter aria-hidden className="size-3.5" />
+        )}
+        {children}
+    </button>
+)
diff --git a/web/mobile/src/features/sessions/SessionListScreen.tsx b/web/mobile/src/features/sessions/SessionListScreen.tsx
index d26eb81608..da4381504a 100644
--- a/web/mobile/src/features/sessions/SessionListScreen.tsx
+++ b/web/mobile/src/features/sessions/SessionListScreen.tsx
@@ -1,7 +1,7 @@
 import {useEffect, useMemo, useState} from "react"
 
+import {FilterChip} from "@/components/FilterChip"
 import {ScreenScaffold} from "@/components/ScreenScaffold"
-import {StatusTag} from "@/components/StatusTag"
 import {clearLastContext} from "@/lib/context"
 
 import {ProjectSwitcher} from "../context/ProjectSwitcher"
@@ -105,8 +105,7 @@ export const SessionListScreen = ({
             <div className="flex flex-col">
                 {onlyPending && pending.unloaded > 0 ? (
                     <p className="text-muted-foreground border-border border-b px-4 py-2 text-xs">
-                        {pending.unloaded} more waiting further down the list — load more to reach{" "}
-                        {pending.unloaded === 1 ? "it" : "them"}.
+                        {pending.unloaded} more further down the list, not loaded yet.
                     </p>
                 ) : null}
                 {rows.map((session) => (
@@ -147,17 +146,17 @@ export const SessionListScreen = ({
                     <ProjectSwitcher workspaceId={workspaceId} projectId={projectId} />
                     <SessionSearchBar value={input} onChange={setInput} />
                     {waitingSessions > 0 ? (
-                        <button
-                            type="button"
-                            aria-pressed={onlyPending}
-                            onClick={() => setOnlyPending((on) => !on)}
-                            className="-m-1 flex min-h-11 items-center gap-2 p-1 text-left"
+                        <FilterChip
+                            active={onlyPending}
+                            onToggle={() => setOnlyPending((on) => !on)}
+                            label={
+                                onlyPending
+                                    ? "Show all sessions"
+                                    : `Show only the ${waitingSessions} session${waitingSessions === 1 ? "" : "s"} waiting on you`
+                            }
                         >
-                            <StatusTag tone="attention">{waitingSessions} waiting</StatusTag>
-                            <span className="text-muted-foreground text-xs underline underline-offset-4">
-                                {onlyPending ? "show all sessions" : "show only these"}
-                            </span>
-                        </button>
+                            {waitingSessions} waiting
+                        </FilterChip>
                     ) : null}
                 </div>
             }
diff --git a/web/mobile/src/features/sessions/states/SessionListStates.tsx b/web/mobile/src/features/sessions/states/SessionListStates.tsx
index 582ad3ba39..ed212f598f 100644
--- a/web/mobile/src/features/sessions/states/SessionListStates.tsx
+++ b/web/mobile/src/features/sessions/states/SessionListStates.tsx
@@ -27,7 +27,7 @@ export const SessionListPendingEmpty = ({
     <div className="flex grow flex-col items-center justify-center gap-3 p-6 text-center">
         <p className="text-muted-foreground text-xs">
             {unloaded > 0
-                ? `${unloaded} session${unloaded === 1 ? "" : "s"} waiting further down the list.`
+                ? `${unloaded} waiting session${unloaded === 1 ? "" : "s"} further down the list, not loaded yet.`
                 : "Nothing waiting on you."}
         </p>
         {unloaded > 0 && canLoadMore ? (

From 64c5706f0d56011438dd9caed67abc3a61e5a036 Mon Sep 17 00:00:00 2001
From: Arda Erzin <ardaerzin@gmail.com>
Date: Mon, 3 Aug 2026 11:22:01 +0300
Subject: [PATCH 17/19] fix(mobile): stop the list header eating the first
 screen
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three stacked full-width rows plus 44px tap targets on text-sized controls left roughly 150px
of chrome above the first session — most of a phone screen's useful top half.

Search and the filter now share a row, since both narrow the same list. The chip and the
project switcher keep their 44px touch targets through an `after` pseudo-element instead of
their own height, so a 32px chip and an 18px switcher row still hit the minimum. Header is
about 84px.

The search input keeps text-base: below 16px iOS zooms the viewport on focus.
---
 web/mobile/src/components/FilterChip.tsx      |  5 ++-
 .../src/features/context/ProjectSwitcher.tsx  |  3 +-
 .../features/sessions/SessionListScreen.tsx   | 34 +++++++++++--------
 .../features/sessions/SessionSearchBar.tsx    |  3 +-
 4 files changed, 27 insertions(+), 18 deletions(-)

diff --git a/web/mobile/src/components/FilterChip.tsx b/web/mobile/src/components/FilterChip.tsx
index 2a0ecb81d7..32673eaaac 100644
--- a/web/mobile/src/components/FilterChip.tsx
+++ b/web/mobile/src/components/FilterChip.tsx
@@ -30,7 +30,10 @@ export const FilterChip = ({
         aria-label={label}
         onClick={onToggle}
         className={cn(
-            "inline-flex min-h-11 shrink-0 items-center gap-1.5 self-start rounded-full border px-3 text-xs font-medium",
+            // 32px tall so it reads as a chip, not a button; `after` extends the touch target to
+            // the 44px minimum without the visual bulk that gave it.
+            "relative inline-flex h-8 shrink-0 items-center gap-1.5 rounded-full border px-2.5 text-xs font-medium",
+            "after:absolute after:-inset-x-1 after:-inset-y-1.5 after:content-['']",
             active
                 ? "border-primary bg-primary text-primary-foreground"
                 : "border-primary/40 text-primary bg-primary/10",
diff --git a/web/mobile/src/features/context/ProjectSwitcher.tsx b/web/mobile/src/features/context/ProjectSwitcher.tsx
index e30d2c484e..1c61bbec5d 100644
--- a/web/mobile/src/features/context/ProjectSwitcher.tsx
+++ b/web/mobile/src/features/context/ProjectSwitcher.tsx
@@ -34,7 +34,8 @@ export const ProjectSwitcher = ({
     return (
         <Link
             href="/?switch=1"
-            className="text-muted-foreground -m-1 flex min-h-11 items-center gap-1.5 p-1 text-xs"
+            // Compact row, full-size touch target: `after` supplies the 44px without the height.
+            className="text-muted-foreground relative flex items-center gap-1.5 self-start py-0.5 text-xs after:absolute after:-inset-x-2 after:-inset-y-2.5 after:content-['']"
         >
             <span className="truncate">
                 {current ? `${current.workspace_name ?? "Workspace"} / ` : ""}
diff --git a/web/mobile/src/features/sessions/SessionListScreen.tsx b/web/mobile/src/features/sessions/SessionListScreen.tsx
index da4381504a..41356ac49a 100644
--- a/web/mobile/src/features/sessions/SessionListScreen.tsx
+++ b/web/mobile/src/features/sessions/SessionListScreen.tsx
@@ -142,22 +142,26 @@ export const SessionListScreen = ({
             scrollRef={scroll.ref}
             onScroll={scroll.onScroll}
             header={
-                <div className="border-border flex shrink-0 flex-col gap-2 border-b p-4">
+                <div className="border-border flex shrink-0 flex-col gap-2 border-b px-4 pt-2 pb-3">
                     <ProjectSwitcher workspaceId={workspaceId} projectId={projectId} />
-                    <SessionSearchBar value={input} onChange={setInput} />
-                    {waitingSessions > 0 ? (
-                        <FilterChip
-                            active={onlyPending}
-                            onToggle={() => setOnlyPending((on) => !on)}
-                            label={
-                                onlyPending
-                                    ? "Show all sessions"
-                                    : `Show only the ${waitingSessions} session${waitingSessions === 1 ? "" : "s"} waiting on you`
-                            }
-                        >
-                            {waitingSessions} waiting
-                        </FilterChip>
-                    ) : null}
+                    {/* Search and filter share a row: both narrow the same list, and three
+                        stacked full-width rows cost most of a phone's first screen. */}
+                    <div className="flex items-center gap-2">
+                        <SessionSearchBar value={input} onChange={setInput} />
+                        {waitingSessions > 0 ? (
+                            <FilterChip
+                                active={onlyPending}
+                                onToggle={() => setOnlyPending((on) => !on)}
+                                label={
+                                    onlyPending
+                                        ? "Show all sessions"
+                                        : `Show only the ${waitingSessions} session${waitingSessions === 1 ? "" : "s"} waiting on you`
+                                }
+                            >
+                                {waitingSessions} waiting
+                            </FilterChip>
+                        ) : null}
+                    </div>
                 </div>
             }
         >
diff --git a/web/mobile/src/features/sessions/SessionSearchBar.tsx b/web/mobile/src/features/sessions/SessionSearchBar.tsx
index 3c48967c22..0b45d3348e 100644
--- a/web/mobile/src/features/sessions/SessionSearchBar.tsx
+++ b/web/mobile/src/features/sessions/SessionSearchBar.tsx
@@ -10,6 +10,7 @@ export const SessionSearchBar = ({
         value={value}
         onChange={(event) => onChange(event.target.value)}
         placeholder="Search sessions"
-        className="border-border bg-background text-foreground placeholder:text-muted-foreground w-full rounded-md border px-3 py-2 text-base"
+        // text-base is deliberate: iOS zooms the viewport on focus below 16px.
+        className="border-border bg-background text-foreground placeholder:text-muted-foreground min-w-0 flex-1 rounded-md border px-3 py-1.5 text-base"
     />
 )

From e05c1d78c87e49674908841208c9c6429de5034e Mon Sep 17 00:00:00 2001
From: Arda Erzin <ardaerzin@gmail.com>
Date: Mon, 3 Aug 2026 12:15:54 +0300
Subject: [PATCH 18/19] fix(mobile): pin the workspace selector to the picker
 header
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The workspace governs everything below it, but it sat inside the scrolling list — with 50
projects it scrolled away, leaving no indication of which workspace the rows belonged to and
no way to change it without scrolling back.

It moves into the pinned header beside the title: chips when there are several, a labelled
name when there is one. The list below becomes the selected workspace's projects, which
also drops the nested section-per-workspace shape it no longer needs.

Splits the old component in three along the way — the selector, the list, and the grouping,
which was an inline useMemo and is now a covered pure function.
---
 .../src/features/context/ContextResolver.tsx  | 43 +++++-----
 .../src/features/context/ProjectList.tsx      | 29 +++++++
 .../features/context/WorkspaceProjectList.tsx | 84 -------------------
 .../features/context/WorkspaceSelector.tsx    | 57 +++++++++++++
 .../src/features/context/contextTarget.ts     |  2 +-
 .../src/features/context/workspaceGroups.ts   | 24 ++++++
 web/mobile/tests/unit/contextTarget.test.ts   |  2 +-
 web/mobile/tests/unit/workspaceGroups.test.ts | 38 +++++++++
 8 files changed, 172 insertions(+), 107 deletions(-)
 create mode 100644 web/mobile/src/features/context/ProjectList.tsx
 delete mode 100644 web/mobile/src/features/context/WorkspaceProjectList.tsx
 create mode 100644 web/mobile/src/features/context/WorkspaceSelector.tsx
 create mode 100644 web/mobile/src/features/context/workspaceGroups.ts
 create mode 100644 web/mobile/tests/unit/workspaceGroups.test.ts

diff --git a/web/mobile/src/features/context/ContextResolver.tsx b/web/mobile/src/features/context/ContextResolver.tsx
index f8cc16bbb4..f3cfa51ad0 100644
--- a/web/mobile/src/features/context/ContextResolver.tsx
+++ b/web/mobile/src/features/context/ContextResolver.tsx
@@ -7,8 +7,10 @@ import {ScreenScaffold} from "@/components/ScreenScaffold"
 import {fetchProjects, readDesktopLastUsed, readLastContext, type LastContext} from "@/lib/context"
 
 import {selectContextTarget} from "./contextTarget"
+import {ProjectList} from "./ProjectList"
 import {SignedOutNotice} from "./states/SignedOutNotice"
-import {WorkspaceProjectList, type WorkspaceGroup} from "./WorkspaceProjectList"
+import {groupByWorkspace, type WorkspaceGroup} from "./workspaceGroups"
+import {WorkspaceSelector} from "./WorkspaceSelector"
 
 const sessionsUrl = ({workspaceId, projectId}: LastContext) =>
     `/w/${workspaceId}/p/${projectId}/sessions`
@@ -36,21 +38,15 @@ export const ContextResolver = () => {
     })
     const result = query.data
 
-    const groups = useMemo<WorkspaceGroup[]>(() => {
-        if (result?.kind !== "ok") return []
-        const byWorkspace = new Map<string, WorkspaceGroup>()
-        for (const project of result.projects) {
-            if (!project.workspace_id) continue
-            const group = byWorkspace.get(project.workspace_id) ?? {
-                workspaceId: project.workspace_id,
-                workspaceName: project.workspace_name ?? "Workspace",
-                projects: [],
-            }
-            group.projects.push(project)
-            byWorkspace.set(project.workspace_id, group)
-        }
-        return [...byWorkspace.values()]
-    }, [result])
+    const groups = useMemo<WorkspaceGroup[]>(
+        () => (result?.kind === "ok" ? groupByWorkspace(result.projects) : []),
+        [result],
+    )
+    // Which workspace the header is scoped to. Falls back rather than syncing on every fetch:
+    // a refetch can drop the selected workspace entirely.
+    const [selectedWorkspaceId, setSelectedWorkspaceId] = useState("")
+    const selectedGroup =
+        groups.find((group) => group.workspaceId === selectedWorkspaceId) ?? groups[0]
 
     const target = useMemo<LastContext | null>(
         () =>
@@ -76,13 +72,18 @@ export const ContextResolver = () => {
         body = <p className="text-muted-foreground grow p-6 text-center text-xs">Loading…</p>
     } else if (result?.kind === "unauthenticated") {
         body = <SignedOutNotice />
-    } else if (result?.kind === "ok" && groups.length > 0) {
+    } else if (result?.kind === "ok" && selectedGroup) {
         header = (
-            <h1 className="border-border shrink-0 border-b p-4 text-xs font-semibold">
-                Choose a project
-            </h1>
+            <div className="border-border flex shrink-0 flex-col gap-2 border-b px-4 pt-3 pb-2">
+                <h1 className="text-xs font-semibold">Choose a project</h1>
+                <WorkspaceSelector
+                    groups={groups}
+                    selectedId={selectedGroup.workspaceId}
+                    onSelect={setSelectedWorkspaceId}
+                />
+            </div>
         )
-        body = <WorkspaceProjectList groups={groups} />
+        body = <ProjectList group={selectedGroup} />
     } else {
         body = (
             <div className="flex grow flex-col items-center justify-center gap-3 p-6 text-center">
diff --git a/web/mobile/src/features/context/ProjectList.tsx b/web/mobile/src/features/context/ProjectList.tsx
new file mode 100644
index 0000000000..5a53b7c7be
--- /dev/null
+++ b/web/mobile/src/features/context/ProjectList.tsx
@@ -0,0 +1,29 @@
+import {useRouter} from "next/router"
+
+import type {WorkspaceGroup} from "./workspaceGroups"
+
+/** Tappable project rows for the selected workspace; the workspace itself is chosen in the header. */
+export const ProjectList = ({group}: {group: WorkspaceGroup}) => {
+    const router = useRouter()
+    return (
+        <div className="flex flex-col gap-2 p-4">
+            {group.projects.map((project) => (
+                <button
+                    key={project.project_id}
+                    type="button"
+                    className="border-border min-h-11 rounded-md border px-3 py-2.5 text-left text-xs"
+                    onClick={() =>
+                        void router.replace(
+                            `/w/${group.workspaceId}/p/${project.project_id}/sessions`,
+                        )
+                    }
+                >
+                    {project.project_name}
+                    {project.is_demo ? (
+                        <span className="text-muted-foreground ml-2">demo</span>
+                    ) : null}
+                </button>
+            ))}
+        </div>
+    )
+}
diff --git a/web/mobile/src/features/context/WorkspaceProjectList.tsx b/web/mobile/src/features/context/WorkspaceProjectList.tsx
deleted file mode 100644
index 01784bd319..0000000000
--- a/web/mobile/src/features/context/WorkspaceProjectList.tsx
+++ /dev/null
@@ -1,84 +0,0 @@
-import {useState} from "react"
-
-import {Building2} from "lucide-react"
-import {useRouter} from "next/router"
-
-import type {MobileProject} from "@/lib/context"
-
-export interface WorkspaceGroup {
-    workspaceId: string
-    workspaceName: string
-    projects: MobileProject[]
-}
-
-/**
- * Project picker, scoped to one workspace at a time.
- *
- * With several workspaces the row of chips IS the workspace selector; with one there is nothing
- * to select, so the same line degrades to a label naming the workspace you are in (the default
- * workspace is called "Default", which reads as a duplicate of a project by that name unless
- * it is labelled).
- */
-export const WorkspaceProjectList = ({groups}: {groups: WorkspaceGroup[]}) => {
-    const router = useRouter()
-    const [selectedId, setSelectedId] = useState(() => groups[0]?.workspaceId ?? "")
-    // Fall back rather than track `groups` in state: a refetch can drop the selected workspace.
-    const selected = groups.find((group) => group.workspaceId === selectedId) ?? groups[0]
-    if (!selected) return null
-
-    return (
-        <div className="flex flex-col gap-4 p-4">
-            {groups.length > 1 ? (
-                <div className="flex flex-col gap-2">
-                    <p className="text-muted-foreground text-xs">Workspace</p>
-                    <div className="-mx-4 flex gap-2 overflow-x-auto px-4 pb-1">
-                        {groups.map((group) => {
-                            const isSelected = group.workspaceId === selected.workspaceId
-                            return (
-                                <button
-                                    key={group.workspaceId}
-                                    type="button"
-                                    aria-pressed={isSelected}
-                                    onClick={() => setSelectedId(group.workspaceId)}
-                                    className={`min-h-11 shrink-0 rounded-md border px-3 text-xs ${
-                                        isSelected
-                                            ? "border-foreground text-foreground"
-                                            : "border-border text-muted-foreground"
-                                    }`}
-                                >
-                                    {group.workspaceName}
-                                </button>
-                            )
-                        })}
-                    </div>
-                </div>
-            ) : (
-                <h2 className="text-muted-foreground flex items-center gap-1.5 text-xs">
-                    <Building2 aria-hidden className="size-3.5 shrink-0" />
-                    <span className="truncate">{selected.workspaceName}</span>
-                    <span className="shrink-0 opacity-70">workspace</span>
-                </h2>
-            )}
-
-            <div className="flex flex-col gap-2">
-                {selected.projects.map((project) => (
-                    <button
-                        key={project.project_id}
-                        type="button"
-                        className="border-border min-h-11 rounded-md border px-3 py-2.5 text-left text-xs"
-                        onClick={() =>
-                            void router.replace(
-                                `/w/${selected.workspaceId}/p/${project.project_id}/sessions`,
-                            )
-                        }
-                    >
-                        {project.project_name}
-                        {project.is_demo ? (
-                            <span className="text-muted-foreground ml-2">demo</span>
-                        ) : null}
-                    </button>
-                ))}
-            </div>
-        </div>
-    )
-}
diff --git a/web/mobile/src/features/context/WorkspaceSelector.tsx b/web/mobile/src/features/context/WorkspaceSelector.tsx
new file mode 100644
index 0000000000..0ea7da1466
--- /dev/null
+++ b/web/mobile/src/features/context/WorkspaceSelector.tsx
@@ -0,0 +1,57 @@
+import {Building2} from "lucide-react"
+
+import type {WorkspaceGroup} from "./workspaceGroups"
+
+/**
+ * The picker's scope control, pinned in the header rather than sitting in the scrolling list —
+ * it governs everything below it, and a project list runs long enough to scroll its own scope
+ * off screen.
+ *
+ * With one workspace there is nothing to select, so it degrades to a label naming where you are
+ * (the default workspace is called "Default", indistinguishable from a project of that name
+ * unless it is labelled).
+ */
+export const WorkspaceSelector = ({
+    groups,
+    selectedId,
+    onSelect,
+}: {
+    groups: WorkspaceGroup[]
+    selectedId: string
+    onSelect: (workspaceId: string) => void
+}) => {
+    if (groups.length <= 1) {
+        const only = groups[0]
+        if (!only) return null
+        return (
+            <p className="text-muted-foreground flex items-center gap-1.5 text-xs">
+                <Building2 aria-hidden className="size-3.5 shrink-0" />
+                <span className="truncate">{only.workspaceName}</span>
+                <span className="shrink-0 opacity-70">workspace</span>
+            </p>
+        )
+    }
+
+    return (
+        <div className="-mx-4 flex gap-2 overflow-x-auto px-4 pb-1">
+            {groups.map((group) => {
+                const isSelected = group.workspaceId === selectedId
+                return (
+                    <button
+                        key={group.workspaceId}
+                        type="button"
+                        aria-pressed={isSelected}
+                        onClick={() => onSelect(group.workspaceId)}
+                        className={`relative h-8 shrink-0 rounded-full border px-3 text-xs font-medium after:absolute after:-inset-x-1 after:-inset-y-1.5 after:content-[''] ${
+                            isSelected
+                                ? "border-foreground text-foreground"
+                                : "border-border text-muted-foreground"
+                        }`}
+                    >
+                        {group.workspaceName}
+                    </button>
+                )
+            })}
+        </div>
+    )
+}
diff --git a/web/mobile/src/features/context/contextTarget.ts b/web/mobile/src/features/context/contextTarget.ts
index f5d1994729..2d4b046181 100644
--- a/web/mobile/src/features/context/contextTarget.ts
+++ b/web/mobile/src/features/context/contextTarget.ts
@@ -1,6 +1,6 @@
 import type {LastContext} from "@/lib/context"
 
-import type {WorkspaceGroup} from "./WorkspaceProjectList"
+import type {WorkspaceGroup} from "./workspaceGroups"
 
 export interface ContextTargetInput {
     /** False until the router has parsed the query string. */
diff --git a/web/mobile/src/features/context/workspaceGroups.ts b/web/mobile/src/features/context/workspaceGroups.ts
new file mode 100644
index 0000000000..b4b269be74
--- /dev/null
+++ b/web/mobile/src/features/context/workspaceGroups.ts
@@ -0,0 +1,24 @@
+import type {MobileProject} from "@/lib/context"
+
+export interface WorkspaceGroup {
+    workspaceId: string
+    workspaceName: string
+    projects: MobileProject[]
+}
+
+/** Group the flat project list by workspace, preserving the server's order within each. */
+export const groupByWorkspace = (projects: MobileProject[]): WorkspaceGroup[] => {
+    const byWorkspace = new Map<string, WorkspaceGroup>()
+    for (const project of projects) {
+        // A project with no workspace cannot be routed to (`/w/:id/p/:id`), so it is dropped.
+        if (!project.workspace_id) continue
+        const group = byWorkspace.get(project.workspace_id) ?? {
+            workspaceId: project.workspace_id,
+            workspaceName: project.workspace_name ?? "Workspace",
+            projects: [],
+        }
+        group.projects.push(project)
+        byWorkspace.set(project.workspace_id, group)
+    }
+    return [...byWorkspace.values()]
+}
diff --git a/web/mobile/tests/unit/contextTarget.test.ts b/web/mobile/tests/unit/contextTarget.test.ts
index 4a927584f7..d35a3d6cc5 100644
--- a/web/mobile/tests/unit/contextTarget.test.ts
+++ b/web/mobile/tests/unit/contextTarget.test.ts
@@ -4,7 +4,7 @@ import {
     selectContextTarget,
     type ContextTargetInput,
 } from "../../src/features/context/contextTarget"
-import type {WorkspaceGroup} from "../../src/features/context/WorkspaceProjectList"
+import type {WorkspaceGroup} from "../../src/features/context/workspaceGroups"
 
 const project = (projectId: string, workspaceId: string) =>
     ({
diff --git a/web/mobile/tests/unit/workspaceGroups.test.ts b/web/mobile/tests/unit/workspaceGroups.test.ts
new file mode 100644
index 0000000000..271cd23c1f
--- /dev/null
+++ b/web/mobile/tests/unit/workspaceGroups.test.ts
@@ -0,0 +1,38 @@
+import {describe, expect, it} from "vitest"
+
+import {groupByWorkspace} from "../../src/features/context/workspaceGroups"
+import type {MobileProject} from "../../src/lib/context"
+
+const project = (projectId: string, workspaceId: string | null, name = "Workspace") =>
+    ({
+        project_id: projectId,
+        project_name: projectId,
+        workspace_id: workspaceId,
+        workspace_name: workspaceId ? name : null,
+    }) as MobileProject
+
+describe("groupByWorkspace", () => {
+    it("groups projects under their workspace, keeping server order", () => {
+        const groups = groupByWorkspace([
+            project("p1", "w1"),
+            project("p2", "w2"),
+            project("p3", "w1"),
+        ])
+
+        expect(groups.map((g) => g.workspaceId)).toEqual(["w1", "w2"])
+        expect(groups[0].projects.map((p) => p.project_id)).toEqual(["p1", "p3"])
+    })
+
+    it("drops a project with no workspace — it cannot be routed to", () => {
+        // The session route is /w/:workspaceId/p/:projectId; without the first half the row
+        // would render as a tap that goes nowhere.
+        expect(groupByWorkspace([project("orphan", null), project("p1", "w1")])).toHaveLength(1)
+    })
+
+    it("falls back to a generic name when the workspace is unnamed", () => {
+        const [group] = groupByWorkspace([
+            {project_id: "p1", project_name: "p1", workspace_id: "w1"} as MobileProject,
+        ])
+        expect(group.workspaceName).toBe("Workspace")
+    })
+})

From b5476ae323349ac763953076f474aac446dadc61 Mon Sep 17 00:00:00 2001
From: Arda Erzin <ardaerzin@gmail.com>
Date: Tue, 4 Aug 2026 01:12:14 +0300
Subject: [PATCH 19/19] docs(mobile): reconcile the design docs with what
 shipped

Review of the plan set found the documents lagging the code in about twenty places. Each
correction was checked against the tree, not against the plan:

- WP0's residual gaps are all implemented. The section is re-headed as the analysis that produced
  the work, and the step text now carries the two things review changed during execution:
  ordering rides `coalesce(updated_at, created_at)` because `updated_at` is nullable and a DESC
  sort puts NULLs first, and the references hydration requires the batch `latest_turn_per_session`
  helper rather than the per-session one, which would make /sessions/query an N+1 path.
- The infra-tail plan's snippets now match the workflow: dispatch inputs through `env:`, exact
  status assertions in the smoke checks, the segment-exact Traefik rule, `pipefail` before the
  piped verifications, and a bounded readiness poll with a cleanup trap instead of `sleep 3`.
- The WP1 plan gains the repo-wide `cd web && pnpm lint-fix` step, the corrected Turbo inputs,
  package-relative paths in the shadcn verification (it runs after `cd web/mobile`), and the dark
  role-map values review actually landed.
- `NoMobilePageWrapper` retires when the gate is turned on, not when its code ships. The design
  doc said the latter, which would leave a mobile visitor with neither the gate nor the blocker.
- The m3 plan states the three event types the endpoint emits, records that the channel's project
  comes from the credential and never the URL, corrects the claim that a session-scoped stream can
  retire the list's project-wide badge polls, and states the unbounded stream age as a known gap
  with its fix rather than as an aside.
- The approvals plan is re-statused as a pre-execution snapshot, since M2 shipped a different
  client payload than it sketches.
- The chat contract's `useApprovalDock` line named an argument the hook does not take and a
  `renderer` it does not return, while omitting `open` and `responding`.
- README: the WP5 status contradiction, the doubled path in the standalone check, a completed
  `.gitignore` chore still listed as pending, the commit count against the review record, and
  `run.sh` invocations that named neither the entrypoint nor the edition.
---
 docs/design/agenta-mobile/README.md           | 29 ++++++-----
 .../agenta-mobile/chat-headless-contract.md   |  2 +-
 docs/design/agenta-mobile/design.md           | 17 +++++--
 ...6-07-12-wp0-sessions-query-and-stamping.md | 21 +++++---
 .../plans/2026-07-12-wp1-mobile-foundation.md | 17 ++++---
 .../plans/2026-07-25-wp1-infra-tail.md        | 51 ++++++++++++++-----
 .../plans/2026-07-26-wp5-device-gate.md       |  4 +-
 .../plans/2026-07-27-m3-live-relay.md         | 43 +++++++++++++---
 .../2026-07-27-mobile-approvals-steering.md   |  8 ++-
 9 files changed, 140 insertions(+), 52 deletions(-)

diff --git a/docs/design/agenta-mobile/README.md b/docs/design/agenta-mobile/README.md
index e357e7c835..1b2962ab42 100644
--- a/docs/design/agenta-mobile/README.md
+++ b/docs/design/agenta-mobile/README.md
@@ -38,9 +38,9 @@ headless chat core shared between desktop and mobile skins).
 | [plans/2026-07-25-wp1-infra-tail.md](./plans/2026-07-25-wp1-infra-tail.md) | WP1 infra tail (prod image CI, compose, run.sh) — **EXECUTED** (Tasks 1-5, 7); fixed the latent entrypoint crash in the unbuilt mobile image. Only the first `workflow_dispatch` publish (Task 7 runbook) is still pending, and it's post-merge by design |
 | [plans/2026-07-26-wp5-device-gate.md](./plans/2026-07-26-wp5-device-gate.md) | WP5 device gate (flag-gated middleware, both directions) — **EXECUTED** (Tasks T1-T7); default-off, T8 banner-retirement deferred to flag-flip |
 
-Wave-2 plans (WP2 auth + project drawer, WP3b mobile chat skin, WP4 product pages, WP5 device
-gate) are **deliberately unwritten** — they must be planned against the real wave-1 code and the
-finalized sessions surface.
+Remaining wave-2 plans (WP2 auth + project drawer, WP3b mobile chat skin, WP4 product pages) are
+**deliberately unwritten** — they must be planned against the real wave-1 code and the finalized
+sessions surface. WP5 is no longer among them: its plan was written and executed (row above).
 
 ## Execution state
 
@@ -65,10 +65,11 @@ What works right now: `cd web && pnpm dev-mobile` → http://localhost:3000/m re
 shell (light+dark from the bridged palette); `pnpm build-mobile` produces a standalone server;
 `pnpm --filter @agenta/mobile lint` enforces the bans + token sync; the dev compose stacks have
 a routable `web-mobile` service (needs a dev-image rebuild to pick up the Dockerfile changes).
-Opt-in in dev too: `run.sh --dev --with-mobile` (originally it rode `with-web` and auto-started,
-but a live dev run showed the second Next dev server pushes an 8GB Docker VM into OOM-killing
-the main web app's first big Turbopack compile — dmesg-confirmed `next-server` kills at ~4.5GB
-RSS. Running both dev servers comfortably wants a 12GB+ VM).
+Opt-in in dev too, from the repo root (swap `--oss` for `--ee` to match the loaded env file):
+`bash ./hosting/docker-compose/run.sh --oss --dev --with-mobile`. Originally it rode `with-web`
+and auto-started, but a live dev run showed the second Next dev server pushes an 8GB Docker VM
+into OOM-killing the main web app's first big Turbopack compile — dmesg-confirmed `next-server`
+kills at ~4.5GB RSS. Running both dev servers comfortably wants a 12GB+ VM.
 
 ### WP0 residual — COMPLETE (2026-07-25, 9 commits, all dual-reviewed)
 
@@ -179,7 +180,8 @@ breakdown and grounding facts.
   produces, because playwright specs are type-checked by the `web/tests` harness, not oss tsc.
   Accepted as precedented noise; the clean fix (excluding `tests/playwright` in
   `web/oss/tsconfig.json`) is a separate cleanup, not part of this WP.
-- Combined six-commit review verdict: **approve**. Every code block landed byte-identical to
+- Combined review verdict across the five commits above plus the T7 documentation commit:
+  **approve**. Every code block landed byte-identical to
   the plan, the desktop matcher regex was independently confirmed correct against the compiled
   middleware manifest (`/m` and `/m/*` excluded; `/models`-style paths still gated), and the
   middleware bundle carries only the gate core (no transitive leaks). Two deferred hardening
@@ -262,7 +264,7 @@ navigation / flows / logic"). All raw-UI; the radix-primitives track re-skins la
 cd web && pnpm install
 pnpm --filter @agenta/mobile lint            # bans + tokens:check
 pnpm --filter @agenta/mobile types:check
-pnpm build-mobile && test -f web/../web/mobile/.next/standalone/mobile/server.js
+pnpm build-mobile && test -f mobile/.next/standalone/mobile/server.js
 pnpm dev-mobile   # → http://localhost:3000/m, check light+dark
 ```
 
@@ -282,10 +284,9 @@ pnpm dev-mobile   # → http://localhost:3000/m, check light+dark
 - **Dev `__env.js`:** the entrypoint mirrors it into the bind-mounted `web/mobile/public/` on
   container start (gitignored). Until the dev image is rebuilt with the P5 Dockerfile changes,
   `/m/__env.js` 404s — harmless console noise.
-- **Chores pending:** `.gitignore` allowlist entries for the `mobile-*` skills (they're tracked
-  via `git add -f`, matching repo precedent — new files inside them would be invisible to
-  `git status` until allowlisted); Fern regen so the FE `include_ended` param stops being a
-  runtime cast.
+- **Chores:** the `.gitignore` allowlist entries for the `mobile-*` skills are **done** (see
+  `.gitignore` — both the `.agents/skills/` and `.claude/skills/` blocks). Still pending: Fern
+  regen so the FE `include_ended` param stops being a runtime cast.
 - **Mobile image CI + publication runbook** (WP1 infra tail, EXECUTED —
   [plans/2026-07-25-wp1-infra-tail.md](./plans/2026-07-25-wp1-infra-tail.md)):
   `.github/workflows/17-check-mobile.yml` build-verifies + smoke-tests the `agenta-web-mobile`
@@ -293,7 +294,7 @@ pnpm dev-mobile   # → http://localhost:3000/m, check light+dark
   in workflow 11) and `@agenta/chat` unit tests (recursive package discovery in workflow 12)
   were already covered by their generic mechanisms — verified, not changed. **First publication
   ordering:** merge → run `17 - check mobile` via `workflow_dispatch` with `push=true,
-  push_latest=true` → only then can operators pass `run.sh --gh --with-mobile`. Until that first
+  push_latest=true` → only then can operators pass `--with-mobile` to `bash ./hosting/docker-compose/run.sh --oss --gh` (or `--ee`). Until that first
   dispatch-push, the `with-web-mobile` compose profile stays opt-in on purpose — `docker compose
   up`/`pull` would fail the whole stack against a `ghcr.io/agenta-ai/agenta-web-mobile:latest`
   that doesn't exist yet.
diff --git a/docs/design/agenta-mobile/chat-headless-contract.md b/docs/design/agenta-mobile/chat-headless-contract.md
index 2c37ad201e..eb56d92e86 100644
--- a/docs/design/agenta-mobile/chat-headless-contract.md
+++ b/docs/design/agenta-mobile/chat-headless-contract.md
@@ -83,7 +83,7 @@ useAgentConversation({entityId, sessionId}): {
 useTurnRenderModel(message, ctx): RenderItem[]        // lifted from AgentMessage.tsx:329-416
 useComposerAttachments({sessionId, limits}): {files, rejections, add, remove, clear, atMax, toParts}
 useSessionHydration({sessionId})
-useApprovalDock({messages, onRespond}): {current, count, respond, approveAll, renderer}
+useApprovalDock({messages, respond}): {open, current, count, responding, respond, approveAll}
 useClientToolDispatch()
 useAgentChatQueue(...)            // exists — moves in
 useAgentModelKeyStatus(...)       // exists — moves in
diff --git a/docs/design/agenta-mobile/design.md b/docs/design/agenta-mobile/design.md
index e1702e9705..92648afc8d 100644
--- a/docs/design/agenta-mobile/design.md
+++ b/docs/design/agenta-mobile/design.md
@@ -111,7 +111,11 @@ provider stack before deciding).
 - Escape hatch both ways: a `agenta-mobile-optout` / `agenta-mobile-optin` cookie set by
   "View desktop site" / "Open mobile version" links; middleware honors it. This also fixes the
   current banner's dismissal-not-persisted annoyance.
-- `NoMobilePageWrapper` is retired once the gate ships.
+- `NoMobilePageWrapper` is retired when the gate is actually turned **on**, not when its code
+  ships. WP5 landed the gate default-off (`AGENTA_MOBILE_GATE`), so retiring the wrapper any
+  earlier would leave a mobile visitor with neither the gate nor the blocker. Retirement (T8)
+  belongs to the deployment window that flips the flag, once WP2 and WP4 can serve what the
+  redirect points at.
 
 **URL scheme (mobile app, under basePath `/m`):**
 
@@ -169,7 +173,14 @@ Mobile consumes this as-is: project-wide list = `querySessions` without a `refer
 per-agent filter = the existing `references` filter; continue-session = resolve the session's
 latest turn (turns endpoints exist) → references → hydrate that revision.
 
-### Residual gaps (the revised WP0 scope)
+### Residual gaps (the revised WP0 scope) — CLOSED, kept as the record of what was scoped
+
+> **Status (2026-07-25): all five items below are implemented.** They are left here as the gap
+> analysis that produced WP0, not as open work. Ordering rides `coalesce(updated_at, created_at)`
+> with a direction-matched id tiebreak, search is an escaped `ilike` on the stream name,
+> references are batch-hydrated by `latest_turn_per_session` (one `DISTINCT ON` query, not
+> per-session), and the zod wire test exists. Only the optional Fern regen for `include_ended`
+> is still outstanding. See the README's "WP0 residual" section for the commit-by-commit record.
 
 1. **`updated_at` ordering/cursor** — the query DAO windows on `id` (uuid7 ≈ creation order);
    the FE sorts client-side per page, which breaks "last-activity" ordering across pages for
@@ -364,7 +375,7 @@ same standard, per the repo's instruction-organization model:
 
 | WP | Scope | Depends on |
 |----|-------|------------|
-| WP0 | BE residual (revised 2026-07-18 — list/title/linkage landed via sessions-extensions): `updated_at` windowing, title search, references echo on list rows, `querySessions` zod test | — |
+| WP0 | **EXECUTED.** BE residual (revised 2026-07-18 — list/title/linkage landed via sessions-extensions): `updated_at` windowing, title search, references echo on list rows, `querySessions` zod test | — |
 | WP1 | Foundation: skill/instruction infrastructure, `web/mobile` scaffold, shadcn + token bridge + motion presets, lint import-bans, compose/Traefik/`__env.js` | — |
 | WP2 | Auth: mobile sign-in (headless SuperTokens + shadcn), callback, context resolution, project drawer | WP1 |
 | WP3a | `@agenta/chat` headless core: lift the behavior blocks (host hook, turn render model, hydration, approvals, attachments neutralization), generalize the registries, fixture tests; OSS re-imports the lifted pure blocks (behavior-neutral) | — |
diff --git a/docs/design/agenta-mobile/plans/2026-07-12-wp0-sessions-query-and-stamping.md b/docs/design/agenta-mobile/plans/2026-07-12-wp0-sessions-query-and-stamping.md
index da8e85aee8..1d5f0439fd 100644
--- a/docs/design/agenta-mobile/plans/2026-07-12-wp0-sessions-query-and-stamping.md
+++ b/docs/design/agenta-mobile/plans/2026-07-12-wp0-sessions-query-and-stamping.md
@@ -89,8 +89,15 @@ scroll. `session_streams.updated_at` is heartbeat-fed last activity.
 """apply_windowing must support `updated_at` as the order/cursor attribute.
 
 The sessions list is ordered by last activity (`updated_at` is heartbeat-fed on
-session_streams). Both ORDER BY and the keyset cursor filters must ride updated_at —
-ordering by updated_at while cursor-filtering on another column paginates incorrectly.
+session_streams). Both ORDER BY and the keyset cursor filters must ride the SAME
+expression — ordering by one column while cursor-filtering on another paginates
+incorrectly.
+
+That expression is `coalesce(updated_at, created_at)`, not bare `updated_at`:
+`updated_at` is nullable, and a DESC sort puts NULLs first in Postgres, so a session
+that never got a heartbeat would sit above every active one. The full statement
+therefore mentions `created_at` by design — assert on the coalesced expression, not on
+the absence of that column.
 """
 
 from datetime import datetime, timezone
@@ -196,10 +203,12 @@ the references *filter*; extend it to hydrate.
 
 **Files**
 - Modify: `api/oss/src/core/sessions/service.py` (`query_sessions` — after fetching streams,
-  batch-fetch the latest turn per session via `SessionTurnsDAO` (one query,
-  `DISTINCT ON (session_id) ... ORDER BY session_id, turn_index DESC` or the DAO's existing
-  latest-turn helper from the turn-index fix `9613e7964e`) and attach `references` (+
-  `trace_id` if cheap) to each row)
+  batch-fetch the latest turn per session via `SessionTurnsDAO` and attach `references` (+
+  `trace_id` if cheap) to each row). This needs a NEW batch helper —
+  `latest_turn_per_session(session_ids)`, one `DISTINCT ON (session_id) ... ORDER BY
+  session_id, turn_index DESC` query. The existing latest-turn helper from the turn-index fix
+  `9613e7964e` takes a single session and would make `/sessions/query` an N+1 path; do not use
+  it here. Keep the one-call assertion in the service test.
 - Modify: response model — either add `references`/`latest_turn` to the session row model the
   root query returns, or wrap rows in an enriched envelope; follow whichever the track's
   maintainer style suggests (read `SessionsResponse` in `api/oss/src/apis/fastapi/sessions/models.py` first)
diff --git a/docs/design/agenta-mobile/plans/2026-07-12-wp1-mobile-foundation.md b/docs/design/agenta-mobile/plans/2026-07-12-wp1-mobile-foundation.md
index 8ed51ba583..be9dc85d5e 100644
--- a/docs/design/agenta-mobile/plans/2026-07-12-wp1-mobile-foundation.md
+++ b/docs/design/agenta-mobile/plans/2026-07-12-wp1-mobile-foundation.md
@@ -27,7 +27,7 @@ Stand up the foundation for the Agenta mobile web app per `docs/design/agenta-mo
 **Tech Stack**
 Next.js `15.5.18` (workspace pin, enforced by the `next@<15.5.18 → >=15.5.18` pnpm override in `web/package.json`), React `^19`, TypeScript `^5.9`, Tailwind CSS v4 (`@tailwindcss/postcss`, CSS-first config — the latest toolchain shadcn supports), shadcn/ui (registry workflow, `new-york` style, CSS variables), `motion` `^12` (same major as OSS), ESLint 9 flat config + Prettier (repo `web/.prettierrc` applies by upward resolution — no new prettier config), pnpm `11.1.2` + turbo `2.8.20`, Docker Compose + Traefik v2.
 
-**Conventions for all commit steps:** run `git branch --show-current` first — if it prints `gitbutler/workspace`, this repo is in GitButler workspace mode and you must use `but branch new <lane>` / `but commit <lane> -m "..."` per root `AGENTS.md`; the commands below assume plain git on a feature branch (e.g. `mobile/wp1-foundation`). Never include Claude/Anthropic/Co-Authored-By lines in commit messages. All commands run from the repo root unless a `cd` is shown.
+**Conventions for all commit steps:** run `git branch --show-current` first — if it prints `gitbutler/workspace`, this repo is in GitButler workspace mode and you must use `but branch new <lane>` / `but commit <lane> -m "..."` per root `AGENTS.md`; the commands below assume plain git on a feature branch (e.g. `mobile/wp1-foundation`). Never include Claude/Anthropic/Co-Authored-By lines in commit messages. All commands run from the repo root unless a `cd` is shown. Before every commit step that touches frontend files, run `cd web && pnpm lint-fix` (the repo-wide convention in `web/AGENTS.md`) — a package-local ESLint run is not a substitute, because the format check in CI runs over the whole `web` tree.
 
 ---
 
@@ -355,8 +355,9 @@ const {sharedAxisPush, sheetSlideUp, crossfade, reduced} = useMotionPresets()
           "public/**",
           "next.config.ts",
           "postcss.config.mjs",
-          "tsconfig.json",
-          "components.json"
+          "$TURBO_DEFAULT$",
+          "!tests/**",
+          "!**/*.md"
       ],
       "outputs": [".next/**", "!.next/cache/**"],
       "env": ["NODE_ENV", "NEXT_PUBLIC_*"]
@@ -786,11 +787,15 @@ const {sharedAxisPush, sheetSlideUp, crossfade, reduced} = useMotionPresets()
       "muted-foreground": [color(p.text.secondary.light), color(p.text.secondary.dark)],
       accent: [
           color(p.surface.controlItemBgActive.light),
-          color(p.surface.controlItemBgActive.dark),
+          // Review delta: the palette's dark controlItemBgActive reads olive against the
+          // mobile surface; zinc[2] is the neutral the dark theme actually wants.
+          color(p.scales.zinc[2].dark),
       ],
       "accent-foreground": [color(p.text.primary.light), color(p.text.primary.dark)],
       destructive: [color(p.semantic.error.light), color(p.semantic.error.dark)],
-      "destructive-foreground": [color(p.surface.white.light), color(p.surface.white.dark)],
+      // Review delta: pure white on the dark destructive fill was too hot; the antd dark
+      // button primary colour is the value the rest of the dark theme uses.
+      "destructive-foreground": [color(p.surface.white.light), p.componentsDark.Button.primaryColor],
       border: [color(p.border.secondary.light), color(p.border.secondary.dark)],
       input: [color(p.border.default.light), color(p.border.default.dark)],
       ring: [color(p.accent.primary.light), color(p.accent.primary.dark)],
@@ -932,7 +937,7 @@ const {sharedAxisPush, sheetSlideUp, crossfade, reduced} = useMotionPresets()
   cd web/mobile && pnpm dlx shadcn@latest add button skeleton
   ```
   Expected: CLI reports it found `components.json`, and creates `src/components/ui/button.tsx` and `src/components/ui/skeleton.tsx`.
-- [ ] Verify: `ls web/mobile/src/components/ui/` → `button.tsx  skeleton.tsx`; `git diff web/mobile/package.json` shows the added radix dep; `web/pnpm-lock.yaml` updated.
+- [ ] Verify (still inside `web/mobile` from the previous step): `ls src/components/ui/` → `button.tsx  skeleton.tsx`; `git diff package.json` shows the added radix dep; `git diff ../pnpm-lock.yaml` shows the lockfile updated.
 
 ### Task 3.9 — Commit the design-system foundation
 
diff --git a/docs/design/agenta-mobile/plans/2026-07-25-wp1-infra-tail.md b/docs/design/agenta-mobile/plans/2026-07-25-wp1-infra-tail.md
index 05fb1de011..72cab5ec0d 100644
--- a/docs/design/agenta-mobile/plans/2026-07-25-wp1-infra-tail.md
+++ b/docs/design/agenta-mobile/plans/2026-07-25-wp1-infra-tail.md
@@ -192,9 +192,15 @@ jobs:
 
       - name: Determine build metadata
         id: meta
+        env:
+          # Through `env` these are only ever data. Interpolated directly into `run:` they
+          # are substituted before bash parses the line, so a value could close the quote
+          # and run commands.
+          PR: ${{ github.event.pull_request.number }}
+          INPUT_TAG: ${{ inputs.image_tag }}
         run: |
-          PR="${{ github.event.pull_request.number }}"
-          INPUT_TAG="${{ inputs.image_tag }}"
+          PR="$PR"
+          INPUT_TAG="$INPUT_TAG"
           SHA="$(git rev-parse --short HEAD)"
 
           if [ -n "$PR" ]; then
@@ -278,12 +284,21 @@ jobs:
             if curl -sf http://127.0.0.1:3000/m >/dev/null; then break; fi
             sleep 1
           done
-          curl -sf http://127.0.0.1:3000/m >/dev/null || { docker logs mobile-smoke; exit 1; }
-          curl -sf http://127.0.0.1:3000/m/__env.js >/dev/null || { docker logs mobile-smoke; exit 1; }
-          # basePath /m owns the prefix: the bare root must 404.
-          if curl -sf http://127.0.0.1:3000/ >/dev/null; then
-            echo "::error::expected / to 404 (basePath /m)"; exit 1
-          fi
+          # Assert the status itself rather than curl's exit code: `-sf` succeeds on a
+          # 3xx (the page never rendered) and fails identically on 404 and 500.
+          expect_status() {
+            local path="$1" want="$2" got
+            got="$(curl -s -o /dev/null -w '%{http_code}' "http://127.0.0.1:3000${path}")"
+            if [ "$got" != "$want" ]; then
+              echo "::error::expected ${path} to return ${want}, got ${got}"
+              docker logs mobile-smoke
+              exit 1
+            fi
+          }
+          expect_status /m 200
+          expect_status /m/__env.js 200
+          # basePath /m owns the prefix, so the bare root belongs to nothing.
+          expect_status / 404
           docker rm -f mobile-smoke
 
       - name: Verify image runs as non-root
@@ -369,10 +384,12 @@ Insert each block **immediately after the `web` service** in its file. All block
         networks:
             - agenta-oss-gh-network
         # === LABELS =============================================== #
-        # PathPrefix(`/m`) auto-wins over the web catch-all PathPrefix(`/`)
-        # by rule length; no stripprefix — the app is built with basePath /m.
+        # Match the `/m` SEGMENT, not every path whose first two characters are `/m`:
+        # a bare PathPrefix(`/m`) would also capture /mobile, /metrics and friends and
+        # steal them from the web catch-all. The rule still auto-wins over PathPrefix(`/`)
+        # by length; no stripprefix — the app is built with basePath /m.
         labels:
-            - "traefik.http.routers.web-mobile.rule=PathPrefix(`/m`)"
+            - "traefik.http.routers.web-mobile.rule=(Path(`/m`) || PathPrefix(`/m/`))"
             - "traefik.http.routers.web-mobile.entrypoints=web"
             - "traefik.http.services.web-mobile.loadbalancer.server.port=3000"
         # === LIFECYCLE ============================================ #
@@ -510,7 +527,9 @@ SHUTDOWN_CMD="$COMPOSE_CMD --profile with-web-mobile --profile with-web --profil
 
 ## Task 5 — Verify (don't change) the already-wired CI coverage
 
-Pin the G3/G5 claims so nobody re-adds duplicate jobs later:
+Pin the G3/G5 claims so nobody re-adds duplicate jobs later. Run `set -o pipefail` first —
+the two piped checks below would otherwise report the exit status of `python3`/`grep` and
+swallow a failing producer:
 
 - [ ] `cd web && pnpm turbo run lint --filter=@agenta/mobile --dry=json | python3 -c "import json,sys; d=json.load(sys.stdin); print([t['taskId'] for t in d['tasks']])"` → includes `@agenta/mobile#lint` (proves `pnpm run lint` in `11-check-code-styling.yml:96` reaches mobile, tokens:check chained).
 - [ ] `cd web && pnpm -r --filter=!agenta-web-tests --if-present run test:unit --reporter=dot 2>&1 | grep -i chat` → `@agenta/chat` suite executes (the exact Phase-1 command from `run-tests.ts:200`); confirm `web/packages/agenta-chat/test-results/junit.xml` exists afterwards (matches the publish glob `12:133-135`).
@@ -534,7 +553,13 @@ docker image ls agenta-web-mobile:smoke --format 'SIZE {{.Size}}'
 
 ```bash
 docker run -d --name mobile-smoke -p 3000:3000 agenta-web-mobile:smoke
-sleep 3
+trap 'docker rm -f mobile-smoke >/dev/null 2>&1' EXIT   # container goes away on failure too
+# Bounded readiness poll, same as the workflow: a fixed sleep races a slow host, where
+# the entrypoint plus the Next server can need well over three seconds.
+for _ in $(seq 1 30); do
+  curl -sf http://127.0.0.1:3000/m >/dev/null && break
+  sleep 1
+done
 curl -sf -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3000/m          # expect: 200
 curl -sf -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3000/m/__env.js # expect: 200
 curl -s  -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3000/           # expect: 404
diff --git a/docs/design/agenta-mobile/plans/2026-07-26-wp5-device-gate.md b/docs/design/agenta-mobile/plans/2026-07-26-wp5-device-gate.md
index eae5078157..97e5b83df0 100644
--- a/docs/design/agenta-mobile/plans/2026-07-26-wp5-device-gate.md
+++ b/docs/design/agenta-mobile/plans/2026-07-26-wp5-device-gate.md
@@ -458,7 +458,9 @@ export function decideMobileGate(input: GateInput): GateDecision {
 }
 ```
 
-- [ ] Run: `cd web && pnpm --filter @agenta/shared test:unit -- mobileGate` — expect **25 passed**.
+- [ ] Run: `cd web && pnpm --filter @agenta/shared test:unit -- mobileGate` — expect **38 passed**
+  (25 at the time this step was written; the file grew with the OAuth-callback handback and the
+  token-bearing `/auth` pass-through). Assert the suite is green, not a fixed number.
 - [ ] Run: `cd web && pnpm --filter @agenta/shared check` — expect types + lint clean.
 - [ ] Commit:
 
diff --git a/docs/design/agenta-mobile/plans/2026-07-27-m3-live-relay.md b/docs/design/agenta-mobile/plans/2026-07-27-m3-live-relay.md
index 9031272dc7..daddffff72 100644
--- a/docs/design/agenta-mobile/plans/2026-07-27-m3-live-relay.md
+++ b/docs/design/agenta-mobile/plans/2026-07-27-m3-live-relay.md
@@ -91,8 +91,17 @@ through the existing (IDB-persisted, deduped) query.
   ApiKey, AND the `sAccessToken` cookie (auth.py:290), and sets
   `request.state.{user_id,project_id}` once at request start — the SSE handler then does the
   same `check_action_access(VIEW_SESSIONS)` as `query_records` (router.py:475-480). Auth is
-  evaluated once at connect; scope holds for the connection's lifetime (standard SSE; cap the
-  connection age server-side if that ever matters).
+  evaluated once at connect; scope holds for the connection's lifetime. That is a real
+  window: revoking a user's `VIEW_SESSIONS` does not close streams they already hold, so
+  they keep receiving change notifications (never payloads — see the wire contract) until
+  they reconnect. **Not bounded as shipped** — there is no maximum stream age today
+  (`env.sessions` carries only `watch_heartbeat_seconds` and `watch_retry_milliseconds`).
+  Accepted for M3 because the stream carries no payloads, only "something changed" for a session
+  the client was already authorized to read, and every revalidation it triggers is a normal
+  authorized request that fails on its own once access is gone. The fix when that is not enough:
+  close the response after a configured max age and let `EventSource` reconnect, which re-runs
+  auth and `check_action_access`. Cheaper than re-checking mid-stream and gives the same upper
+  bound on staleness.
 - Proxy path: Traefik routes `/api` → api:8000 with a strip-prefix middleware only
   (`hosting/docker-compose/oss/docker-compose.dev.yml:188-194`); no custom responding
   timeouts configured. Heartbeats every ~15s keep any idle timeout (Traefik or client) happy.
@@ -215,7 +224,14 @@ domain layering per api/AGENTS.md.
   Log-and-continue on publish failure — persistence is already committed and must not be
   re-driven by relay errors. Unit test with fakeredis: batch with 2 sessions ⇒ 2 publishes,
   each after append; append failure ⇒ no publish for that batch.
-- **T2 — SSE watch endpoint.** `GET /sessions/streams/watch?session_id=` on the
+- **T2 — SSE watch endpoint.** Three event types, not one: `records-changed`
+  (`{session_id}`), `lifecycle` (`{session_id, state: "running"|"ended"}`) and
+  `interaction` (`{session_id, status: "pending"|"resolved"}`). Each names the query the
+  client should revalidate — records, liveness, and actionable interactions respectively —
+  so a client can retire the matching poll. A payload shape that cannot distinguish them
+  would let the mobile task revalidate records only, and the liveness and approval badges
+  would go stale while the stream looked healthy.
+  `GET /sessions/streams/watch?session_id=` on the
   `StreamsRouter` (`api/oss/src/apis/fastapi/sessions/router.py`): `check_action_access`
   (`VIEW_SESSIONS`, mirroring router.py:475-480), validate `session_id`
   (contract.py:121-131), then `StreamingResponse(media_type="text/event-stream")` that
@@ -240,6 +256,15 @@ domain layering per api/AGENTS.md.
   open ⇒ slow safety-net poll (30s); SSE errored/unsupported ⇒ today's 4s/7.5s cadence
   unchanged (the fallback IS the current behavior — no regression path).
 
+### Tenant selection
+
+The URL carries `session_id` ONLY. `project_id` comes from `request.state.project_id`,
+set by the auth middleware, and the channel is built from that. A `project_id` in the
+query string would be a tenant selector supplied by the caller: passing another project's
+id would subscribe the caller to that project's channel, and the `VIEW_SESSIONS` check
+would have been run against a different project than the one being watched. The client
+task must not add it to the URL.
+
 ### Deferred (explicitly not in M3)
 
 - **Desktop consumption** — wire the same SSE into `revalidateSessionRecordsAtom` +
@@ -265,7 +290,11 @@ domain layering per api/AGENTS.md.
 1. **Paragraph-level (~1-2s) change-notification SSE: YES** for the current iteration.
    Token-by-token streaming (runner Redis client + per-delta publishing) stays rejected —
    revisit only if a future product need demands cursor-level liveness on mobile.
-2. **Lifecycle events on the same channel: YES** — the watch stream also carries turn
-   lifecycle (running/ended/approval-pending), so mobile retires all three polls
-   (records tick, liveness, actionable-interactions) in favor of one EventSource; the
-   polls remain as the documented no-regression fallback when the stream is down.
+2. **Lifecycle events on the same channel: YES, but only for the open session** — the
+   watch stream also carries turn lifecycle (running/ended/approval-pending), so an open
+   chat can drop its own records tick, liveness poll and actionable-interactions poll in
+   favor of one EventSource. The channel is `(project_id, session_id)`, so it says nothing
+   about the OTHER sessions in the project: `SessionListScreen`'s liveness and
+   pending-approval badges cover every row and MUST keep their project-wide polls. A
+   project-scoped lifecycle stream would be needed to retire those, and it is not in M3.
+   The polls also remain the documented no-regression fallback when the stream is down.
diff --git a/docs/design/agenta-mobile/plans/2026-07-27-mobile-approvals-steering.md b/docs/design/agenta-mobile/plans/2026-07-27-mobile-approvals-steering.md
index f1586ba98c..b88e820226 100644
--- a/docs/design/agenta-mobile/plans/2026-07-27-mobile-approvals-steering.md
+++ b/docs/design/agenta-mobile/plans/2026-07-27-mobile-approvals-steering.md
@@ -1,6 +1,12 @@
 # Mobile approvals + steering — design & plan
 
-**Status:** PLANNED · **Date:** 2026-07-27 · **Branch:** `feat/agenta-mobile-wave-1`
+**Status:** HISTORICAL PRE-EXECUTION SNAPSHOT (M0-M3 executed; see [../README.md](../README.md))
+· **Date:** 2026-07-27 · **Branch:** `feat/agenta-mobile-wave-1`
+
+> Read this as the plan as written, not as a description of what shipped. The one contract
+> difference worth knowing before reading further: the client answers a gate with
+> `{approved}` through the detached respond dispatcher, not the payload sketched below, and
+> the "no producer" / unverified notes in §3 were resolved during execution.
 **Goal:** from a phone, on a session whose agent runs in the cloud: (1) see that a turn is
 running and an approval is pending with enough context to decide, (2) approve/deny and have the
 agent proceed, (3) stop, and steer where feasible — all WITHOUT being the SSE stream holder.