fix: constrain dialog content to the viewport

- Add dynamic viewport bounds and scrollable body regions to dialogs and modals\n- Make tool-launch popups use the shared scrollable body pattern\n- Keep mobile sheets, action sheets, and notification popups scroll-contained\n- Restore the ProjectsPage test setup required for the frontend suite\n\nOpenSpec: fix-dialog-scroll-containment\nQuality gates: npm run typecheck, npm run lint, npm test (88 passed), npm run build

apps/api/src/services/terminal/terminal_session.py

@@ -19,6 +19,8 @@ from typing import Any
 
 logger = logging.getLogger(__name__)
 
+_session_counters_by_instance: dict[str, int] = {}
+
 
 class TerminalSession:
     """Manages a single terminal session with event-driven PTY I/O.
@@ -46,9 +48,6 @@ class TerminalSession:
     # Max WebSocket frame size
     MAX_FRAME_SIZE = 64 * 1024
 
-    # Session number counter per instance_id for auto-naming
-    _instance_counters: dict[str, int] = {}
-
     def __init__(
         self,
         session_id: str,
@@ -99,11 +98,11 @@ class TerminalSession:
         # Ack timeout fallback
         self._ack_timeout_handle: asyncio.TimerHandle | None = None
 
-    @classmethod
+    @staticmethod
-    def _generate_name(cls, instance_id: str) -> str:
+    def _generate_name(instance_id: str) -> str:
         """Generate an auto-incremented session name for the instance."""
-        count = cls._instance_counters.get(instance_id, 0) + 1
+        count = _session_counters_by_instance.get(instance_id, 0) + 1
-        cls._instance_counters[instance_id] = count
+        _session_counters_by_instance[instance_id] = count
         return f"Session {count}"
 
     async def start(self, startup_command: str | None = None) -> None:
@@ -121,8 +120,12 @@ class TerminalSession:
         if self.container_user:
             exec_cmd.extend(["--user", self.container_user])
 
-        # Create a pseudo-terminal on the host
+        # Create a pseudo-terminal on the host. The master must be
+        # non-blocking: a browser paste can be larger than the PTY input
+        # buffer, and write_input() drains it asynchronously without dropping
+        # the closing bracketed-paste marker.
         self._master_fd, slave_fd = pty.openpty()
+        os.set_blocking(self._master_fd, False)
 
         # Put the host PTY into raw mode so it behaves as a pass-through
         # pipe. openpty() leaves the slave in canonical mode by default,
@@ -204,6 +207,9 @@ class TerminalSession:
 
         try:
             data = os.read(self._master_fd, 4096)
+        except BlockingIOError:
+            # The readiness notification raced with another callback.
+            return
         except (OSError, IOError) as exc:
             logger.debug("PTY read error for session %s: %s", self.session_id, exc)
             self._handle_eof()
@@ -343,12 +349,42 @@ class TerminalSession:
                 pass
         logger.info("Session %s EOF handled, websockets closed", self.session_id)
 
+    async def _wait_for_write_ready(self, fd: int) -> None:
+        """Wait until a non-blocking PTY master can accept more input."""
+        loop = asyncio.get_running_loop()
+        writable = loop.create_future()
+
+        def mark_writable() -> None:
+            if not writable.done():
+                writable.set_result(None)
+
+        loop.add_writer(fd, mark_writable)
+        try:
+            await writable
+        finally:
+            loop.remove_writer(fd)
+
     async def write_input(self, data: bytes) -> None:
-        """Write input to the PTY master."""
+        """Write all terminal input bytes to the PTY master in order."""
         if self._master_fd is None or self._closed:
             return
+
+        fd = self._master_fd
+        remaining = memoryview(data)
         try:
-            os.write(self._master_fd, data)
+            while remaining and not self._closed and self._master_fd == fd:
+                try:
+                    written = os.write(fd, remaining)
+                except BlockingIOError:
+                    await self._wait_for_write_ready(fd)
+                    continue
+
+                if written == 0:
+                    await self._wait_for_write_ready(fd)
+                    continue
+
+                remaining = remaining[written:]
+
             self.last_activity = time.time()
         except (OSError, IOError) as exc:
             logger.debug("PTY write error for session %s: %s", self.session_id, exc)

apps/api/tests/unit/test_terminal_session.py

@@ -1,9 +1,9 @@
-"""Unit tests for TerminalSession docker exec invocation."""
+"""Unit tests for TerminalSession PTY handling."""
 
 import uuid
 from unittest.mock import AsyncMock, patch
 
-import pytest
+import pytest  # pyright: ignore[reportMissingImports]
 
 from src.services.terminal.terminal_session import TerminalSession
 
@@ -19,17 +19,20 @@ async def test_start_passes_container_user_to_docker_exec() -> None:
         container_user="dev",
     )
 
-    with patch(
+    with (
-        "src.services.terminal.terminal_session.pty.openpty",
+        patch(
-        return_value=(1, 2),
+            "src.services.terminal.terminal_session.pty.openpty",
+            return_value=(1, 2),
+        ),
+        patch("src.services.terminal.terminal_session.os.set_blocking") as set_blocking,
+        patch("src.services.terminal.terminal_session.tty.setraw"),
+        patch(
+            "src.services.terminal.terminal_session.asyncio.create_subprocess_exec",
+            new=AsyncMock(),
+        ) as mock_exec,
+        patch("src.services.terminal.terminal_session.os.close"),
     ):
-        with patch("src.services.terminal.terminal_session.tty.setraw"):
+        await session.start()
-            with patch(
-                "src.services.terminal.terminal_session.asyncio.create_subprocess_exec",
-                new=AsyncMock(),
-            ) as mock_exec:
-                with patch("src.services.terminal.terminal_session.os.close"):
-                    await session.start()
 
     args, _kwargs = mock_exec.call_args
     assert "docker" in args
@@ -38,6 +41,7 @@ async def test_start_passes_container_user_to_docker_exec() -> None:
     user_index = args.index("--user")
     assert args[user_index + 1] == "dev"
     assert "container-123" in args
+    set_blocking.assert_called_once_with(1, False)
 
 
 @pytest.mark.unit
@@ -50,17 +54,44 @@ async def test_start_omits_user_when_not_configured() -> None:
         container_id="container-123",
     )
 
-    with patch(
+    with (
-        "src.services.terminal.terminal_session.pty.openpty",
+        patch(
-        return_value=(1, 2),
+            "src.services.terminal.terminal_session.pty.openpty",
+            return_value=(1, 2),
+        ),
+        patch("src.services.terminal.terminal_session.os.set_blocking"),
+        patch("src.services.terminal.terminal_session.tty.setraw"),
+        patch(
+            "src.services.terminal.terminal_session.asyncio.create_subprocess_exec",
+            new=AsyncMock(),
+        ) as mock_exec,
+        patch("src.services.terminal.terminal_session.os.close"),
     ):
-        with patch("src.services.terminal.terminal_session.tty.setraw"):
+        await session.start()
-            with patch(
-                "src.services.terminal.terminal_session.asyncio.create_subprocess_exec",
-                new=AsyncMock(),
-            ) as mock_exec:
-                with patch("src.services.terminal.terminal_session.os.close"):
-                    await session.start()
 
     args, _kwargs = mock_exec.call_args
     assert "--user" not in args
+
+
+@pytest.mark.unit
+@pytest.mark.asyncio
+async def test_write_input_retries_partial_pty_writes() -> None:
+    """A large paste is fully written even when the PTY accepts it in chunks."""
+    session = TerminalSession(
+        session_id=str(uuid.uuid4()),
+        instance_id=uuid.uuid4(),
+        container_id="container-123",
+    )
+    session._master_fd = 42
+
+    with patch(
+        "src.services.terminal.terminal_session.os.write",
+        side_effect=[2, 2, 1],
+    ) as write:
+        await session.write_input(b"hello")
+
+    assert [bytes(call.args[1]) for call in write.call_args_list] == [
+        b"hello",
+        b"llo",
+        b"o",
+    ]

apps/web/src/components/features/tool/instance-list.tsx

@@ -578,19 +578,23 @@ export const InstanceList = ({
 			{showCreate && (
 				<div className="dialog-overlay" role="dialog" aria-modal="true">
 					<div className="dialog">
-						<h2>Launch Tool</h2>
+						<div className="dialog-header">
-						<CreateSessionForm
+							<h2>Launch Tool</h2>
-							projects={[]}
+						</div>
-							repositories={[]}
+						<div className="dialog-body">
-							toolTypes={toolTypes}
+							<CreateSessionForm
-							fixedProjectId={projectId}
+								projects={[]}
-							fixedRepoId={repoId}
+								repositories={[]}
-							projectName={projectName}
+								toolTypes={toolTypes}
-							repoName={repoName}
+								fixedProjectId={projectId}
-							onSuccess={handleCreateSuccess}
+								fixedRepoId={repoId}
-							onCancel={() => setShowCreate(false)}
+								projectName={projectName}
-							submitLabel="Launch"
+								repoName={repoName}
-						/>
+								onSuccess={handleCreateSuccess}
+								onCancel={() => setShowCreate(false)}
+								submitLabel="Launch"
+							/>
+						</div>
 					</div>
 				</div>
 			)}

apps/web/src/components/features/tool/start-tool-fab.tsx

@@ -62,6 +62,7 @@ export function StartToolFAB() {
 							</button>
 						</div>
 
+						<div className="modal-body">
 						{workspacesLoading ? (
 							<p className="muted">Loading workspaces...</p>
 						) : workspaces.length === 0 ? (
@@ -110,6 +111,7 @@ export function StartToolFAB() {
 								/>
 							</>
 						)}
+						</div>
 					</div>
 				</div>
 			)}

apps/web/src/components/features/workspace/workspace-tools-panel.test.tsx

@@ -0,0 +1,47 @@
+import "@testing-library/jest-dom/vitest";
+import { fireEvent, render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+
+import { WorkspaceToolsPanel } from "./workspace-tools-panel";
+import type { Workspace } from "../../../types/workspace";
+
+vi.mock("../../../hooks/use-workspace-instances", () => ({
+  useWorkspaceInstances: () => ({
+    instances: [],
+    loading: false,
+    refresh: vi.fn(),
+  }),
+}));
+
+vi.mock("../tool/tool-starter", () => ({
+  ToolStarter: () => <div data-testid="tool-starter" />,
+}));
+
+const workspace: Workspace = {
+  id: "workspace-1",
+  name: "Main",
+  repo_id: "repo-1",
+  repo_name: "repository",
+  repo_ssh_key_id: null,
+  project_id: "project-1",
+  project_name: "Project",
+  user_id: "user-1",
+  branch: "main",
+  path: "/workspace",
+  status: "ready",
+  last_sync_at: null,
+  created_at: "2026-01-01T00:00:00Z",
+  updated_at: "2026-01-01T00:00:00Z",
+  instance_count: 0,
+};
+
+describe("WorkspaceToolsPanel", () => {
+  it("places the tool launcher inside the shared scrollable dialog body", () => {
+    const { container } = render(<WorkspaceToolsPanel workspace={workspace} />);
+
+    fireEvent.click(screen.getByRole("button", { name: "Start Tool" }));
+
+    const dialogBody = container.querySelector(".dialog-body");
+    expect(dialogBody).toContainElement(screen.getByTestId("tool-starter"));
+  });
+});

apps/web/src/components/features/workspace/workspace-tools-panel.tsx

@@ -64,15 +64,19 @@ export function WorkspaceToolsPanel({ workspace }: WorkspaceToolsPanelProps) {
 			{showModal && (
 				<div className="dialog-overlay" onClick={() => setShowModal(false)}>
 					<div className="dialog" onClick={(e) => e.stopPropagation()}>
-						<h3>Start Tool</h3>
+						<div className="dialog-header">
-						<ToolStarter
+							<h3>Start Tool</h3>
-							workspace={workspace}
+						</div>
-							onStarted={() => {
+						<div className="dialog-body">
-								setShowModal(false);
+							<ToolStarter
-								void refresh();
+								workspace={workspace}
-							}}
+								onStarted={() => {
-							onCancel={() => setShowModal(false)}
+									setShowModal(false);
-						/>
+									void refresh();
+								}}
+								onCancel={() => setShowModal(false)}
+							/>
+						</div>
 					</div>
 				</div>
 			)}

apps/web/src/pages/ProjectsPage.test.tsx

@@ -1,17 +1,26 @@
+import "@testing-library/jest-dom/vitest";
 import { cleanup, fireEvent, render, screen, waitFor, within } from "@testing-library/react";
 import { MemoryRouter } from "react-router-dom";
 import { afterEach, describe, expect, it, vi } from "vitest";
 
 import { ProjectsPage } from "./ProjectsPage";
 import * as projectsApi from "../api/projects";
+import { SessionsProvider } from "../state/sessions";
+import type { ProjectWithRepos } from "../types";
 
-const mockProjects = [
+vi.mock("../api/sessions", () => ({
+  getUserSessions: vi.fn().mockResolvedValue([]),
+}));
+
+const mockProjects: ProjectWithRepos[] = [
   {
     id: "proj-1",
     name: "Alpha Project",
     description: "First project",
     owner_id: "user-1",
     default_ssh_key_id: null,
+    repositories: [],
+    created_at: "2026-07-01T00:00:00Z",
   },
   {
     id: "proj-2",
@@ -19,6 +28,8 @@ const mockProjects = [
     description: null,
     owner_id: "user-1",
     default_ssh_key_id: null,
+    repositories: [],
+    created_at: "2026-07-01T00:00:00Z",
   },
 ];
 
@@ -31,9 +42,7 @@ describe("ProjectsPage", () => {
   it("renders loading state initially", () => {
     vi.spyOn(projectsApi, "listProjects").mockImplementation(() => new Promise(() => {}));
     render(
-      <MemoryRouter>
+      <MemoryRouter><SessionsProvider><ProjectsPage /></SessionsProvider></MemoryRouter>
-        <ProjectsPage />
-      </MemoryRouter>
     );
     expect(screen.getByText(/loading projects/i)).toBeInTheDocument();
   });
@@ -41,9 +50,7 @@ describe("ProjectsPage", () => {
   it("renders project list after loading", async () => {
     vi.spyOn(projectsApi, "listProjects").mockResolvedValue(mockProjects);
     render(
-      <MemoryRouter>
+      <MemoryRouter><SessionsProvider><ProjectsPage /></SessionsProvider></MemoryRouter>
-        <ProjectsPage />
-      </MemoryRouter>
     );
 
     await waitFor(() => {
@@ -56,9 +63,7 @@ describe("ProjectsPage", () => {
   it("renders empty state when no projects", async () => {
     vi.spyOn(projectsApi, "listProjects").mockResolvedValue([]);
     render(
-      <MemoryRouter>
+      <MemoryRouter><SessionsProvider><ProjectsPage /></SessionsProvider></MemoryRouter>
-        <ProjectsPage />
-      </MemoryRouter>
     );
 
     await waitFor(() => {
@@ -69,9 +74,7 @@ describe("ProjectsPage", () => {
   it("renders error state with retry button", async () => {
     vi.spyOn(projectsApi, "listProjects").mockRejectedValue(new Error("fail"));
     render(
-      <MemoryRouter>
+      <MemoryRouter><SessionsProvider><ProjectsPage /></SessionsProvider></MemoryRouter>
-        <ProjectsPage />
-      </MemoryRouter>
     );
 
     await waitFor(() => {
@@ -85,9 +88,7 @@ describe("ProjectsPage", () => {
     const createMock = vi.spyOn(projectsApi, "createProject").mockResolvedValue(mockProjects[0]);
 
     render(
-      <MemoryRouter>
+      <MemoryRouter><SessionsProvider><ProjectsPage /></SessionsProvider></MemoryRouter>
-        <ProjectsPage />
-      </MemoryRouter>
     );
 
     await waitFor(() => {
@@ -118,9 +119,7 @@ describe("ProjectsPage", () => {
     vi.spyOn(projectsApi, "listProjects").mockResolvedValue([]);
 
     render(
-      <MemoryRouter>
+      <MemoryRouter><SessionsProvider><ProjectsPage /></SessionsProvider></MemoryRouter>
-        <ProjectsPage />
-      </MemoryRouter>
     );
 
     await waitFor(() => {
@@ -138,16 +137,14 @@ describe("ProjectsPage", () => {
     const updateMock = vi.spyOn(projectsApi, "updateProject").mockResolvedValue(mockProjects[0]);
 
     render(
-      <MemoryRouter>
+      <MemoryRouter><SessionsProvider><ProjectsPage /></SessionsProvider></MemoryRouter>
-        <ProjectsPage />
-      </MemoryRouter>
     );
 
     await waitFor(() => {
       expect(screen.getByText("Alpha Project")).toBeInTheDocument();
     });
 
-    const alphaCard = screen.getByText("Alpha Project").closest(".project-card") as HTMLElement | null;
+    const alphaCard = screen.getByText("Alpha Project").closest(".project-list-item") as HTMLElement | null;
     if (!alphaCard) throw new Error("Card not found");
 
     fireEvent.click(within(alphaCard).getByRole("button", { name: /edit/i }));
@@ -171,16 +168,14 @@ describe("ProjectsPage", () => {
     const deleteMock = vi.spyOn(projectsApi, "deleteProject").mockResolvedValue(undefined);
 
     render(
-      <MemoryRouter>
+      <MemoryRouter><SessionsProvider><ProjectsPage /></SessionsProvider></MemoryRouter>
-        <ProjectsPage />
-      </MemoryRouter>
     );
 
     await waitFor(() => {
       expect(screen.getByText("Alpha Project")).toBeInTheDocument();
     });
 
-    const alphaCard = screen.getByText("Alpha Project").closest(".project-card") as HTMLElement | null;
+    const alphaCard = screen.getByText("Alpha Project").closest(".project-list-item") as HTMLElement | null;
     if (!alphaCard) throw new Error("Card not found");
 
     fireEvent.click(within(alphaCard).getByRole("button", { name: /delete/i }));

apps/web/src/styles/global.css

@@ -453,12 +453,16 @@
 	backdrop-filter: blur(2px);
 }
 
-.dialog {
+.dialog,
+.modal-content,
+.commit-dialog {
 	width: 100%;
 	max-width: 32rem;
 	max-height: calc(100vh - var(--space-8));
+	max-height: calc(100dvh - var(--space-8));
 	display: flex;
 	flex-direction: column;
+	min-height: 0;
 	overflow: hidden;
 	background: var(--panel);
 	border: 1px solid var(--border);
@@ -468,16 +472,6 @@
 
 .modal-content {
 	/* deprecated alias */
-	width: 100%;
-	max-width: 32rem;
-	max-height: calc(100vh - var(--space-8));
-	display: flex;
-	flex-direction: column;
-	overflow: hidden;
-	background: var(--panel);
-	border: 1px solid var(--border);
-	border-radius: var(--radius-lg);
-	box-shadow: var(--shadow-xl);
 }
 
 .dialog-lg {
@@ -500,9 +494,13 @@
 	line-height: var(--line-height-tight);
 }
 
-.dialog-body {
+.dialog-body,
+.modal-body {
 	flex: 1;
+	min-height: 0;
 	overflow: auto;
+	overscroll-behavior: contain;
+	-webkit-overflow-scrolling: touch;
 	padding: var(--space-4);
 }
 
@@ -543,9 +541,11 @@
 	}
 
 	.dialog,
-	.modal-content {
+	.modal-content,
+	.commit-dialog {
 		max-width: 100%;
 		max-height: calc(100vh - var(--space-6));
+		max-height: calc(100dvh - var(--space-6));
 		border-radius: var(--radius-lg) var(--radius-lg) 0 0;
 	}
 }

apps/web/src/styles/utilities.css

@@ -2328,8 +2328,10 @@ a.nav-item,
 	width: 100%;
 	max-width: 600px;
 	max-height: 70vh;
+	max-height: 70dvh;
 	display: flex;
 	flex-direction: column;
+	min-height: 0;
 	animation: slide-up 0.2s ease-out;
 }
 
@@ -2365,8 +2367,12 @@ a.nav-item,
 }
 
 .mobile-bottom-sheet-content {
+	flex: 1;
+	min-height: 0;
 	padding: 8px 0;
 	overflow-y: auto;
+	overscroll-behavior: contain;
+	-webkit-overflow-scrolling: touch;
 }
 
 .mobile-bottom-sheet-item {
@@ -3240,7 +3246,10 @@ a:active,
 	width: 100%;
 	max-width: 500px;
 	max-height: 80vh;
+	max-height: 80dvh;
 	overflow-y: auto;
+	overscroll-behavior: contain;
+	-webkit-overflow-scrolling: touch;
 	animation: slideUp 0.3s ease;
 	padding-bottom: env(safe-area-inset-bottom, 0);
 }
@@ -3602,6 +3611,7 @@ a:active,
 		max-width: none;
 		border-radius: 12px;
 		max-height: 70vh;
+		max-height: 70dvh;
 	}
 }
 

openspec/changes/fix-dialog-scroll-containment/change.md

@@ -0,0 +1,28 @@
+# Constrain and Scroll Edit Dialogs and Popups
+
+## Summary
+
+Ensure every edit dialog, form popup, and modal popup remains usable on a viewport that is shorter than its content. Dialog chrome must stay within the visible viewport while the content area scrolls independently.
+
+## Problem
+
+The shared dialog system constrains only components that follow its `dialog-header` / `dialog-body` structure. Several tool-launch and commit dialogs place form content directly inside the container or use a bespoke container, so long forms can be clipped. Existing viewport sizing also relies on `vh`, which is unreliable when mobile browser chrome changes height.
+
+## Scope
+
+- Shared dialog and modal CSS in `apps/web/src/styles/global.css`.
+- Mobile notification dropdown sizing in `apps/web/src/styles/utilities.css`.
+- Tool-launch and commit popup markup that does not currently provide a scrollable content region.
+
+## Acceptance Criteria
+
+- [ ] Dialogs and modal popups are bounded by the current visible viewport, including mobile dynamic viewport changes.
+- [ ] Headers and footer/action bars remain visible while long form content scrolls independently.
+- [ ] Tool-launch and commit popups use the shared scrollable content pattern.
+- [ ] Mobile sheets, action sheets, and notification dropdowns remain scrollable without propagating scroll gestures to the page.
+- [ ] Relevant frontend tests, typecheck, lint, and production build pass.
+
+## Non-Goals
+
+- Redesigning dialog visuals or interaction flows.
+- Changing page-level scrolling outside overlays.

openspec/changes/fix-dialog-scroll-containment/tasks.md

@@ -0,0 +1,8 @@
+# Constrain and Scroll Edit Dialogs and Popups — Tasks
+
+- [x] Audit all dialog, modal, sheet, action-sheet, and popup implementations.
+- [x] Strengthen shared dialog/modal viewport and body scrolling rules.
+- [x] Update bespoke tool-launch and commit popups to use scrollable content regions.
+- [x] Add focused coverage for the shared scrollable dialog-body markup.
+- [x] Run frontend typecheck, lint, tests (88 passed), and production build.
+- [x] Update project maps for changed source files.