From b0b3e97ec32c022d8e86003877af14c9b07c3f82 Mon Sep 17 00:00:00 2001
From: Jayanth Vasupilli <156448548+jayanthvee@users.noreply.github.com>
Date: Thu, 15 Oct 2026 15:52:20 -0700
Subject: [PATCH 01/12] docs(tickets): add PL-023 and PL-025 with the design
 rules and the approved Home mock

PL-023 rebuilds apps/web as React + TypeScript in the approved look. PL-025 restyles the extension popup in the same language. D-023 records the owner's mandate that the admin panel lives in its own repository sharing this database through a least-privilege role.
---
 internal/agent/tickets/PL-023.md    | 112 +++++++++++++
 internal/agent/tickets/PL-025.md    |  51 ++++++
 internal/docs/DECISIONS.md          |   1 +
 internal/docs/DESIGN.md             | 157 +++++++++++++++++++
 internal/docs/design/home-mock.html | 234 ++++++++++++++++++++++++++++
 5 files changed, 555 insertions(+)
 create mode 100644 internal/agent/tickets/PL-023.md
 create mode 100644 internal/agent/tickets/PL-025.md
 create mode 100644 internal/docs/DESIGN.md
 create mode 100644 internal/docs/design/home-mock.html

diff --git a/internal/agent/tickets/PL-023.md b/internal/agent/tickets/PL-023.md
new file mode 100644
index 0000000..a3ac9aa
--- /dev/null
+++ b/internal/agent/tickets/PL-023.md
@@ -0,0 +1,112 @@
+# PL-023: The web app — shell, Home, Tasks, Runs and Needs help
+
+Owner: T2 · Reviewer: T1 · Depends on: PL-022 (merged) · Phase: D
+
+## Description
+The brief needs a real web app. `apps/web` is still the bare operator page from PL-015. This ticket rebuilds
+`apps/web` in **React + TypeScript + Vite**, the stack the brief names, in the approved look, and delivers the
+screens that use data we already have.
+
+**Read these first, and follow them exactly:**
+- `internal/docs/DESIGN.md`: the words, type, color tokens, layout, sidebar and motion;
+- `internal/docs/design/home-mock.html`: the approved Home screen. Open it in a browser. Port its CSS tokens and
+  structure; don't reinvent them.
+
+**The user is not technical.** The UI vocabulary table in DESIGN.md §2 is mandatory. No engine word (recipe,
+record key, parked, ledger, version) may appear on any screen. A unit test enforces this (requirement 7).
+
+## Requirements
+1. **The stack.**
+   - React 18, React Router and TypeScript in `apps/web`, built by Vite into `apps/web/dist`, which
+     `services/api/main.py` already serves.
+   - Plain CSS with the DESIGN.md tokens (one `tokens.css` plus CSS modules or co-located CSS). **No Tailwind,
+     no component library.**
+   - Public Sans through `@fontsource/public-sans`.
+   - Pin every new dependency to an exact version.
+   - Keep `npm --prefix apps/web run check` (typecheck, test, build) as the gate.
+2. **The app shell.**
+   - The sidebar exactly as in DESIGN.md §6. Every item routes to a page.
+   - The header: page title, search (Ctrl K opens a simple search over task names; a stub list is fine), the
+     page's primary action, and the avatar.
+   - The "Chrome connected" status comes from the hub's session state (whether a session is attached); show
+     "Chrome not connected" otherwise.
+   - Pages not built in this ticket (Spreadsheets, Documents, Saved answers, Apps, Settings, Help) show a
+     designed empty state: one sentence plus "Coming soon". No blank pages.
+3. **Home** matches the mock, backed by real data:
+   - the headline "N rows done this week. M need you." (with no rows: "Nothing has run yet." and the Teach
+     button);
+   - **time saved this week** (rows done × 3 minutes, minus run time), shown in the gold figure exactly as in the mock;
+   - Needs your help (top 3);
+   - Running now, with a live progress bar (poll every 2 s while a run is active);
+   - My tasks (latest 5).
+4. **Tasks** (`/tasks`):
+   - A table of the saved recipes, shown as tasks: name, the app (from the recipe's first allowed origin),
+     last run, result, and one button ("Run again" or "Try one row"). Empty state: "Teach your first task" →
+     a link to `/teach`, a "Coming next" page.
+   - Clicking a task opens `/tasks/:id`, a read-only page for now: its steps in plain words (a navigate step
+     becomes "Open Odoo CRM", a fill becomes "Type the email", and so on) and its runs. The editor comes in
+     PL-024.
+5. **Runs** (`/runs` and `/runs/:id`):
+   - **The list:** task, started, status, and "11 of 20 done".
+   - **A run page** with:
+     - live progress;
+     - pause, resume and cancel;
+     - a results table: each row's name or key, its outcome in plain words and the reason;
+     - **Export CSV**, using the existing `results.csv`.
+   - Time saved for a finished run: rows done × 3 minutes, minus the run's duration. Show it as "About 52
+     minutes saved".
+6. **Needs help** (`/needs-help`):
+   - Every row across runs that needs a person, with the plain reason and one action:
+     - **Try again**: re-queue.
+     - **Dismiss**.
+   - **Safety (unchanged from PL-015, mandatory):** a row that may already have been saved (any commit was
+     attempted) can only be re-queued after the person ticks "I checked Odoo and it isn't there". The API
+     enforces this already. The UI must show the checkbox and explain why.
+   - The Home and sidebar counts come from the same source.
+7. **No engine words on screen.**
+   - Add a vitest that renders every page with sample data and fails if the visible text contains any of:
+     `recipe`, `ledger`, `parked`, `record key`, `verified`, `rung`, `idempotency`, `v1`, `v2`, `step_`,
+     `fill-`, `click-`.
+   - Each forbidden word maps to the plain wording in DESIGN.md §2.
+8. **The API, only what the pages need.**
+   - Add `GET /api/v1/home`, which returns the week's counts (done, already there, needs help), the minutes
+     saved, the needs-help top 3, the running runs with their progress, and the latest tasks. Use one module in
+     `services/api`, following `internal/docs/sql-patterns.md`, with pytest tests.
+   - Reuse the existing `/runs`, `/recipes`, `/records/*` and `/approvals` routes for everything else.
+   - **No change** to the ledger, runner, hub protocol, or the re-queue safety check.
+9. **Motion and accessibility.**
+   - The blur-in entrance runs on first render only. Live updates ease. Everything is off under reduced motion.
+   - All buttons are real `<button>` or `<a>` elements with visible focus. The pages are usable at 400 px wide.
+
+## Out of scope
+Teach, the task editor, spreadsheet upload and check, try-one-row, Documents, the landing page, sign-in and
+Railway. Those are the next tickets.
+
+## Acceptance criteria
+- [ ] Gates:
+  - `npm --prefix apps/web run check`
+  - `python -m pytest -q`
+  - `ruff check .` and `ruff format --check .`
+  - `npm --prefix apps/extension run check` (it must stay green)
+- [ ] `services/api` serves the built app at `/`. Every sidebar route loads, with no console errors.
+- [ ] The report (`internal/agent/reports/PL-022.md` style, at `internal/agent/reports/PL-023.md`) lists each page
+  with what data it shows. **No screenshots needed: T1 tests in the browser.**
+
+## T2 operating rules for this ticket
+- **Sub-agents** run on deepseek-flash only. Builders use thinking high and `max_steps` 80; the coordinator stays
+  on thinking low. Don't choose other models.
+- **Split the builders by disjoint files:**
+  - builder A: the app shell, tokens and router;
+  - builder B: Home and the `/api/v1/home` endpoint;
+  - builder C: Tasks and Runs;
+  - builder D: Needs help and the engine-word test.
+
+  Run them one after another where files overlap. A goes first.
+- **No e2e runs** and no plan stop. Stop only for:
+  - a ledger, runner, hub or re-queue safety change;
+  - an out-of-scope change;
+  - three identical failures.
+- On Windows, never use `2>&1` or the PowerShell `&` call operator. Scratch files go only under `.cache/` or
+  `.data/`.
+- Use conventional commits with no AI attribution. Never commit the root `docker-compose.yml` or
+  `internal/docs/TEST-MOCK/`. Push the branch and stop for T1.
diff --git a/internal/agent/tickets/PL-025.md b/internal/agent/tickets/PL-025.md
new file mode 100644
index 0000000..473e1d1
--- /dev/null
+++ b/internal/agent/tickets/PL-025.md
@@ -0,0 +1,51 @@
+# PL-025: The extension popup in the app's design language
+
+Owner: T2 · Reviewer: T1 · Depends on: PL-023 (merged) · Phase: D
+
+## Description
+The Chrome extension's popup is what a person sees while teaching a task, so it must look and speak like the
+web app. Apply `internal/docs/DESIGN.md` to `apps/extension/src/popup/`: Public Sans, the light fog, glass
+surfaces, the gold primary button, and the plain words. This is a restyle and re-wording. **No behaviour
+changes.**
+
+## Requirements
+1. **Look.**
+   - The tokens are a copy of the web app's `tokens.css`, under `apps/extension/src/popup/`.
+   - **Light only.** Popup width stays as it is now.
+   - Public Sans is **bundled with the extension** (`@fontsource/public-sans` woff2 files copied into `dist`).
+     The extension's CSP must not load remote fonts.
+2. **Words.** Use the DESIGN.md §2 vocabulary.
+   - "Make recipe" → **"Save as task"**.
+   - "record key" → **"Which column identifies each row?"**
+   - "allowed origins" → **"Sites this task may use"**.
+   - Recorder warnings are rewritten as plain sentences.
+   - Show steps as plain sentences: "Typed the email", "Clicked Save".
+3. **The layout, top to bottom:**
+   - connection status ("Connected to ProcessLens" or "Not connected");
+   - the big **Start teaching** / **Stop** button;
+   - the live list of recorded steps;
+   - after stopping, the Save-as-task form with one gold primary button.
+4. **The e2e contract is frozen.**
+   - Every element id, `data-state` value and `data-testid` the e2e harness uses must keep its exact name and
+     meaning: `#start`, `#stop`, `#clear`, `#state`, `#session-state`, and the make-recipe form's ids. Grep
+     `tests/e2e/conftest.py` and the e2e tests for every selector, and list them in the report.
+   - Only text and styles change.
+5. **Tests.**
+   - Update the popup vitest expectations for the new wording.
+   - Add the same engine-word check as PL-023 requirement 7, run over the popup's rendered text.
+
+## Out of scope
+Recorder, executor and service-worker logic. The web app.
+
+## Acceptance criteria
+- [ ] `npm --prefix apps/extension run check` passes: typecheck, test, build and validate.
+- [ ] The report lists every e2e selector and confirms it is unchanged. T1 runs the e2e tests and looks at the
+  popup.
+
+## T2 operating rules for this ticket
+- Sub-agents run on deepseek-flash only. Builders use thinking high and `max_steps` 80; the coordinator stays
+  low.
+- No e2e runs and no plan stop. Stop only for a change outside `apps/extension/src/popup/` and its tests, or
+  three identical failures.
+- On Windows, never use `2>&1` or the `&` call operator. Scratch files go only under `.cache/` or `.data/`.
+- Use conventional commits with no AI attribution. Push the branch and stop for T1.
diff --git a/internal/docs/DECISIONS.md b/internal/docs/DECISIONS.md
index 4d680d4..ea68639 100644
--- a/internal/docs/DECISIONS.md
+++ b/internal/docs/DECISIONS.md
@@ -27,3 +27,4 @@ Entries are never edited after acceptance; a later entry supersedes an earlier o
 | D-020 | Supersedes the layer numbering in D-019, and records the recording-first order: the recorder comes first, before AI. The recorder captures what changed rather than the events it hears (state-diff recording, PL-018), so the layers now read: AI suggestions and summary (PL-019), verification (PL-020), self-healing (PL-021). D-019's rules stand unchanged: built-in compiler rules first, each AI suggestion carries its reason, the person is asked where the rules and the AI disagree, the person confirms every rule, preview and canary verify every new or changed recipe, locator repair is proposed from parked records and approved by a person, and AI never runs inside a batch (D-017 stands) | A recorder that trusts specific DOM events misses editors, autofill, keyboard selection, paste, IME and password managers; state-diff capture makes the recording the source of truth every later layer builds on, and the AI layers move behind it | Accepted (owner) | 2026-10-14 |
 | D-021 | Hosting: Railway runs the API, the workers, Postgres and the web app | The choice was Vercel or Railway. Vercel cannot hold the hub's WebSocket connection and cannot run long-lived workers, and those are the two constraints this system actually has; Railway runs both, with a managed Postgres beside them in the same project | Accepted (owner) | 2026-10-15 |
 | D-022 | Test targets: real open-source apps run locally in Docker (Odoo 18 Community and Twenty CRM, PL-022) replace the hand-built mock sites as the main targets for recording and replay. The mocks stay for unit-level fixture tests | Pages we wrote ourselves contain only the bugs we already thought of. Real software brings autocompletes, inline editing, command menus and duplicate checks that nobody here wrote, so replay is tested against software we do not control. The mocks stay because unit and fixture tests need a target that cannot drift under them | Accepted (owner) | 2026-10-15 |
+| D-023 | The admin panel lives in its own repository (owner's mandate), sharing the ProcessLens database through a separate, least-privilege Postgres role. Schema and migrations stay owned by this repo; the admin repo never runs migrations. Supersedes D-018 for the admin panel only | Owner's mandate. The admin panel is a separate deliverable with its own access surface, while the schema and its migrations stay in exactly one place and the admin repository reaches the database only through a role that can do what the panel needs and nothing more | Accepted (owner) | 2026-10-15 |
diff --git a/internal/docs/DESIGN.md b/internal/docs/DESIGN.md
new file mode 100644
index 0000000..c06a0a8
--- /dev/null
+++ b/internal/docs/DESIGN.md
@@ -0,0 +1,157 @@
+# ProcessLens web app — design rules
+
+The reference is the approved mock: https://claude.ai/artifact/BioXAntzA4B5FwQTzYUJoW (version 5). When this
+file and the mock disagree, this file wins. Follow these rules for every screen.
+
+## 1. Who it is for
+
+The user does repetitive data entry. They are not technical. If a screen needs an explanation, it is wrong.
+- Show **one obvious next action** per item.
+- Show **at most one primary button** per screen. It is the near-black one.
+- If something went wrong, say what happened and what to do, in one sentence.
+
+## 2. Words (UI vocabulary)
+
+The engine's words never appear on screen. Use the right-hand column.
+
+| Engine / code | On screen |
+|---|---|
+| workflow, recipe | **task** |
+| recipe version vN | not shown (Task history shows "Changed on 14 Oct") |
+| run | **run** ("Run again", "Runs") |
+| record, row | **row**, or the person's or thing's name when there is one ("Priya Nair") |
+| verified | **added**, **updated** or **done** (the task's verb) |
+| skipped (duplicate) | **already there** |
+| parked | **needs your help** |
+| failed | **didn't work**, plus the reason |
+| submitting / reconciling | **checking…** |
+| record key, input schema, step id, rung, ledger | never shown |
+| value_mappings | **saved answers** |
+| allowed origins | **sites this task may use** |
+
+Rules for copy:
+- Use sentence case.
+- Name things by what they are ("Odoo CRM", "your spreadsheet").
+- Write "Choose salesperson", not "Resolve".
+
+## 3. Type
+
+- **Public Sans** only, self-hosted with `@fontsource/public-sans`, weights 300, 400, 500 and 600. There is no
+  second font, and no monospace in the UI.
+- Never use uppercase labels or letter-spaced eyebrows.
+- Numbers use `font-variant-numeric: tabular-nums`.
+
+| Role | Size and weight | Notes |
+|---|---|---|
+| Page headline | 34–52 px, weight 300 | tracking −0.04em, line-height 1.04 |
+| Second line of a headline | same as above | in `--muted` |
+| Section and panel titles | 15 px, weight 600 | |
+| Body | 14.5 px, weight 400 | |
+| Secondary text | 13–14 px | `--ink-2` |
+| Meta | 13 px | `--muted` |
+
+## 4. Color tokens (CSS custom properties on `:root`)
+
+**Light only** (the owner's call, 2026-10-15). Don't follow the OS dark mode. Copy the values from the mock.
+
+**Gold is the one accent:**
+- `--gold`, `--gold-deep`, `--gold-soft` and `--gold-line`;
+- the primary button is a soft gold gradient (`--primary-a` to `--primary-b`) with dark text (`--on-primary`);
+- progress bars use the same gradient;
+- the **time saved** figure is in `--gold-deep` on a `--gold-soft` panel.
+
+Gold is never used for text blocks or backgrounds.
+
+**Text:** soft charcoal, not black. `--ink` is `#2a2d2b`.
+
+**Background:**
+- `--fog-1`, `--fog-2` and `--fog-3` form the page background: two soft radial fogs over a vertical gradient,
+  fixed to the page. The light values are near-white: `#fbfcfc`, `#f1f4f3`, `#e3e8e6`.
+
+**Surfaces:**
+- `--glass`, `--glass-line` and `--glass-strong` are the frosted panels: white at 72% / 90% / 92%, with
+  `backdrop-filter: blur(18px)`.
+
+**Text:**
+- `--ink` (primary), `--ink-2` (secondary), `--muted` (meta).
+- `--hair` and `--hair-2` are the dividers.
+
+**Primary button:**
+- `--primary` (near-black) with `--on-primary`.
+
+**State, always shown as a dot plus a word, never alone:**
+- `--ok` for done;
+- `--help` for needs your help;
+- `--live` for running;
+- `--muted` for idle or already there.
+
+**Banned:**
+- the fonts Inter, Space Grotesk, Manrope, Playfair Display and Lora;
+- warm paper backgrounds;
+- purple-to-blue gradients;
+- pill chips and tag clouds;
+- card grids;
+- Tailwind default styling;
+- uppercase mono eyebrows.
+
+## 5. Layout
+
+- **The app shell:**
+  - a frosted **sidebar**, 216 px wide;
+  - a **header** with the page title on the left, then Search (Ctrl K), the page's one primary action, and the
+    avatar;
+  - the **content column**, at most 1180 px wide.
+- **Panels:** frosted glass, 14 px radius, a 1 px light border, and a very soft shadow.
+  - Panels are for **groups of rows**, never for decoration.
+  - Never put more than **2 panels side by side**.
+- **Lists and tables:** rows separated by hairlines, 12–14 px vertical padding.
+  - Each row: a title (weight 500), one line of explanation, and **one** quiet button on the right.
+  - Tables have at most 4–5 columns. No sorting UI, no filter tabs and no ⋯ menus unless the screen truly needs
+    them.
+- **Empty states:** one sentence about what will appear here, and the one button that makes it appear.
+- **Phone width** (under 780 px): the sidebar becomes a top strip, the panels stack, and minor columns hide.
+
+## 6. Sidebar (information architecture)
+
+```
+Home
+Needs help        (count, amber, only when > 0)
+— Automate
+Tasks             taught tasks; opens the task (steps · spreadsheet columns · rules · history)
+Runs              every run, live and past; opens the run (progress · results)
+— Your data
+Spreadsheets      uploaded CSVs and their check (the brief's "input review")
+Documents         PDFs (résumés, invoices) and what was read from them
+Saved answers     e.g. "R. Iyer" → "Ravi Iyer"; reused on later runs
+— Connect
+Apps              Odoo, Twenty …; the sites each task may use; the Chrome extension's status
+(bottom)
+Settings          workspace, people, how long screenshots are kept, approval rules
+Help
+Chrome connected  live extension status
+```
+
+Group labels are plain 12 px muted text, not capitals.
+
+## 7. Motion
+
+- **On page load, sections blur in, in order:** `opacity 0 → 1`, `filter: blur(10px) → 0` and
+  `translateY(8px) → 0`, over 850 ms with `cubic-bezier(.2,.7,.2,1)`, staggered 70 ms apart. Only on the first
+  render of a page, never on data refresh.
+- **Live data:** progress bars ease their width (900 ms). The "Live" dot pulses. New rows in a live list rise in
+  with a 5 px blur.
+- **Hover:** the primary button lifts 1 px; rows get a faint glass highlight. Nothing bounces or scales.
+- Under `prefers-reduced-motion`, every animation is off, and everything stays visible at rest.
+
+## 8. The core flow (from the brief, in this order)
+
+1. **Teach.** Pick the app tab, record, stop. You see the steps in plain words.
+2. **Task page.**
+   - Steps: rename, remove and reorder them.
+   - Spreadsheet columns: which recorded value comes from which column.
+   - Rules: what happens if it's already there, if a value is missing, or if an option doesn't exist.
+3. **Spreadsheet check.** Upload, see the problems flagged per row, fix them inline.
+4. **Try one row.** Watch it run, see the exact values it is about to save, then approve.
+5. **Run.** Live progress; "needs your help" items appear as they happen.
+6. **Results.** Done, already there, needs help and didn't work, each with its reason. Time saved compared with
+   doing it by hand. Export.
diff --git a/internal/docs/design/home-mock.html b/internal/docs/design/home-mock.html
new file mode 100644
index 0000000..04be9a3
--- /dev/null
+++ b/internal/docs/design/home-mock.html
@@ -0,0 +1,234 @@
+<title>ProcessLens Dashboard Mock</title>
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Public+Sans:wght@300;400;500;600&display=swap">
+<style>
+/* Layout: light "Fog" with a slim frosted sidebar (4 places) and one main column:
+   header (title, search, one primary action) -> headline -> two panels (needs you | running) -> a simple tasks table.
+   Fewer things on screen; each item has one plain action. */
+/* Deliberately light-only: an internal tool used all day in an office. Gold is the one accent. */
+:root {
+  color-scheme: light;
+  --fog-1: #fdfdfc; --fog-2: #f4f5f3; --fog-3: #e9ebe6;
+  --glass: rgba(255,255,255,.78); --glass-line: rgba(255,255,255,.95); --glass-strong: rgba(255,255,255,.95);
+  --ink: #2a2d2b; --ink-2: #5d6461; --muted: #959c98; --hair: rgba(42,45,43,.07); --hair-2: rgba(42,45,43,.13);
+  --gold: #c8a04a; --gold-deep: #9c7a2c; --gold-soft: #f7f0de; --gold-line: #e8d6aa;
+  --primary-a: #d9b663; --primary-b: #c59a3f; --on-primary: #2b2210;
+  --ok: #3d7a55; --help: #b0532c; --live: #b8892f;
+  --font: "Public Sans", "Helvetica Neue", Arial, sans-serif;
+}
+
+* { box-sizing: border-box; }
+html, body { min-height: 100%; }
+body {
+  margin: 0; color: var(--ink); font: 14.5px/1.5 var(--font); -webkit-font-smoothing: antialiased;
+  background:
+    radial-gradient(1200px 560px at 10% -10%, var(--fog-1) 0%, transparent 60%),
+    radial-gradient(1000px 640px at 105% 105%, var(--fog-3) 0%, transparent 62%),
+    linear-gradient(180deg, var(--fog-1), var(--fog-2));
+  background-attachment: fixed; background-color: var(--fog-2);
+}
+:focus-visible { outline: 2px solid var(--ink-2); outline-offset: 2px; border-radius: 6px; }
+svg.i { width: 16px; height: 16px; flex: none; fill: none; stroke: currentColor; stroke-width: 1.5; stroke-linecap: round; stroke-linejoin: round; }
+
+.app { display: grid; grid-template-columns: 216px minmax(0, 1fr); min-height: 100vh; }
+
+/* sidebar: four places, then settings and the extension at the bottom */
+.side { position: sticky; top: 0; height: 100vh; padding: 16px 12px; display: flex; flex-direction: column; gap: 22px;
+  background: var(--glass); backdrop-filter: blur(18px); -webkit-backdrop-filter: blur(18px); border-right: 1px solid var(--glass-line); }
+.logo { display: flex; align-items: center; gap: 9px; font-weight: 600; font-size: 15px; padding: 2px 8px; }
+.logo svg { width: 21px; height: 21px; }
+.nav { display: grid; gap: 2px; }
+.nav a { display: flex; align-items: center; gap: 10px; padding: 8px 10px; border-radius: 8px; color: var(--ink-2); text-decoration: none; font-weight: 500; }
+.nav a:hover { background: var(--hair); color: var(--ink); }
+.nav a.on { background: var(--glass-strong); color: var(--ink); box-shadow: 0 1px 2px rgba(0,0,0,.04), inset 0 0 0 1px var(--hair); }
+.nav .n { margin-left: auto; font-size: 12px; font-weight: 600; color: var(--help); }
+.navs { display: grid; gap: 4px; overflow-y: auto; }
+.grp { font-size: 12px; color: var(--muted); padding: 12px 10px 4px; }
+.side-foot { margin-top: auto; display: grid; gap: 8px; }
+.ext { display: flex; gap: 9px; align-items: center; padding: 8px 10px; font-size: 13px; color: var(--ink-2); }
+.ext i { width: 8px; height: 8px; border-radius: 50%; background: var(--ok); flex: none; box-shadow: 0 0 0 3px color-mix(in srgb, var(--ok) 16%, transparent); }
+
+/* main */
+main { min-width: 0; padding: 16px clamp(16px, 3vw, 40px) 64px; display: grid; gap: 30px; align-content: start; max-width: 1180px; }
+.head { display: flex; align-items: center; gap: 12px; min-height: 44px; flex-wrap: wrap; }
+.head h2 { margin: 0; font-size: 15px; font-weight: 600; }
+.search { margin-left: auto; display: flex; align-items: center; gap: 8px; width: min(300px, 40vw); padding: 8px 11px; border-radius: 9px; border: 1px solid var(--hair-2); background: var(--glass-strong); color: var(--muted); font-size: 13.5px; }
+.search kbd { margin-left: auto; font: 500 11px var(--font); border: 1px solid var(--hair-2); border-radius: 4px; padding: 0 5px; color: var(--ink-2); }
+.avatar { width: 32px; height: 32px; border-radius: 50%; background: var(--glass-strong); border: 1px solid var(--hair-2); display: grid; place-items: center; font-size: 12px; font-weight: 600; }
+.btn { display: inline-flex; align-items: center; gap: 8px; font: 500 14px var(--font); border-radius: 9px; padding: 9px 14px; cursor: pointer; border: 1px solid transparent; text-decoration: none; white-space: nowrap; transition: transform .15s ease; }
+.btn.primary { background: linear-gradient(180deg, var(--primary-a), var(--primary-b)); color: var(--on-primary); box-shadow: inset 0 1px 0 rgba(255,255,255,.35), 0 1px 2px rgba(120,90,20,.2), 0 8px 18px -10px rgba(120,90,20,.45); }
+.saved-fig { text-align: right; display: grid; gap: 2px; padding: 14px 20px; border-radius: 14px; background: linear-gradient(180deg, rgba(255,255,255,.85), var(--gold-soft)); border: 1px solid var(--gold-line); }
+.saved-fig b { font-size: clamp(30px, 3.4vw, 42px); font-weight: 300; letter-spacing: -0.035em; color: var(--gold-deep); font-variant-numeric: tabular-nums; line-height: 1.05; }
+.saved-fig span { color: var(--ink-2); font-size: 13.5px; }
+.saved-fig small { color: var(--muted); font-size: 12.5px; }
+.hero { display: flex; justify-content: space-between; align-items: flex-end; gap: 24px; flex-wrap: wrap; }
+.btn.primary:hover { transform: translateY(-1px); }
+.btn.quiet { background: var(--glass-strong); color: var(--ink); border-color: var(--hair-2); padding: 7px 12px; font-size: 13.5px; }
+.btn.quiet:hover { border-color: var(--ink-2); }
+
+.big { margin: 6px 0 0; font-size: clamp(34px, 4.2vw, 52px); font-weight: 300; letter-spacing: -0.04em; line-height: 1.04; }
+.big span { color: var(--muted); }
+.lede { margin: 12px 0 0; color: var(--ink-2); font-size: 15.5px; }
+
+.panel { background: var(--glass); backdrop-filter: blur(18px); -webkit-backdrop-filter: blur(18px); border: 1px solid var(--glass-line); border-radius: 14px;
+  box-shadow: 0 1px 1px rgba(0,0,0,.02), 0 18px 40px -30px rgba(0,0,0,.28); min-width: 0; }
+.panel-h { display: flex; align-items: center; justify-content: space-between; gap: 12px; padding: 15px 20px 6px; }
+.panel-h h3 { margin: 0; font-size: 15px; font-weight: 600; }
+.panel-h a { color: var(--ink-2); font-size: 13.5px; text-decoration: none; }
+.panel-h a:hover { color: var(--ink); }
+.two { display: grid; grid-template-columns: minmax(0, 1.3fr) minmax(0, 1fr); gap: 18px; }
+
+.rows { list-style: none; margin: 0; padding: 0 0 6px; }
+.rows li { display: grid; grid-template-columns: minmax(0,1fr) auto; gap: 14px; align-items: center; padding: 12px 20px; border-top: 1px solid var(--hair); }
+.rows li:first-child { border-top: 0; }
+.rows b { font-weight: 500; }
+.rows p { margin: 1px 0 0; color: var(--ink-2); font-size: 14px; }
+
+.run { padding: 10px 20px 20px; display: grid; gap: 12px; }
+.run b { font-weight: 500; font-size: 15px; }
+.track { height: 6px; border-radius: 6px; background: var(--hair-2); overflow: hidden; }
+.track i { display: block; height: 100%; width: 0; background: linear-gradient(90deg, var(--primary-a), var(--primary-b)); border-radius: 6px; transition: width .9s cubic-bezier(.3,.1,.2,1); }
+.run .meta { display: flex; justify-content: space-between; gap: 12px; color: var(--ink-2); font-size: 13.5px; font-variant-numeric: tabular-nums; }
+.live { display: inline-flex; align-items: center; gap: 7px; color: var(--live); font-size: 13px; font-weight: 500; }
+.live i { width: 6px; height: 6px; border-radius: 50%; background: var(--live); animation: pulse 1.8s ease-out infinite; }
+@keyframes pulse { 0% { box-shadow: 0 0 0 0 color-mix(in srgb, var(--live) 55%, transparent); } 70%, 100% { box-shadow: 0 0 0 6px transparent; } }
+
+table { width: 100%; border-collapse: collapse; }
+th { text-align: left; font-weight: 500; font-size: 13px; color: var(--muted); padding: 10px 20px; border-bottom: 1px solid var(--hair); }
+td { padding: 14px 20px; border-bottom: 1px solid var(--hair); vertical-align: middle; }
+tbody tr:last-child td { border-bottom: 0; }
+tbody tr:hover { background: color-mix(in srgb, var(--glass-strong) 75%, transparent); }
+td b { font-weight: 500; display: block; }
+td small { color: var(--muted); font-size: 13px; }
+.res { display: inline-flex; align-items: center; gap: 8px; }
+.res::before { content: ""; width: 7px; height: 7px; border-radius: 50%; background: currentColor; }
+.res.ok { color: var(--ok); } .res.help { color: var(--help); } .res.live { color: var(--live); } .res.idle { color: var(--muted); }
+td.act { text-align: right; width: 1%; white-space: nowrap; }
+
+.in { animation: blurin .85s cubic-bezier(.2,.7,.2,1) both; animation-delay: calc(var(--i, 0) * 70ms); }
+@keyframes blurin { from { opacity: 0; filter: blur(10px); transform: translateY(8px); } }
+@media (prefers-reduced-motion: reduce) { .in, .live i { animation: none !important; } .track i { transition: none; } }
+
+@media (max-width: 1040px) { .two { grid-template-columns: minmax(0,1fr); } }
+@media (max-width: 780px) {
+  .app { grid-template-columns: minmax(0,1fr); }
+  .side { position: static; height: auto; flex-direction: row; align-items: center; border-right: 0; border-bottom: 1px solid var(--glass-line); overflow-x: auto; }
+  .side .nav { grid-auto-flow: column; }
+  .navs { grid-auto-flow: column; align-items: center; }
+  .grp { display: none; }
+  .side-foot, .search { display: none; }
+  th:nth-child(2), td:nth-child(2) { display: none; }
+}
+</style>
+
+<svg width="0" height="0" style="position:absolute" aria-hidden="true">
+  <symbol id="i-home" viewBox="0 0 16 16"><path d="M2.5 7 8 2.5 13.5 7v6.5h-11z"/><path d="M6.5 13.5V9.5h3v4"/></symbol>
+  <symbol id="i-tasks" viewBox="0 0 16 16"><rect x="2.5" y="2.5" width="11" height="11" rx="2"/><path d="M5.5 6h5M5.5 8.5h5M5.5 11h3"/></symbol>
+  <symbol id="i-hist" viewBox="0 0 16 16"><path d="M2.8 8a5.2 5.2 0 1 0 1.5-3.7"/><path d="M2.5 2.8v2.4h2.4M8 5.2V8l2 1.4"/></symbol>
+  <symbol id="i-help" viewBox="0 0 16 16"><circle cx="8" cy="8" r="5.5"/><path d="M8 5v3.4M8 10.8v.1"/></symbol>
+  <symbol id="i-sheet" viewBox="0 0 16 16"><rect x="2.5" y="2.5" width="11" height="11" rx="1.5"/><path d="M2.5 6.2h11M2.5 9.8h11M6.4 2.5v11"/></symbol>
+  <symbol id="i-doc" viewBox="0 0 16 16"><path d="M4 2.5h5.5L12 5v8.5H4z"/><path d="M9.5 2.5V5H12M6 8.5h4M6 11h3"/></symbol>
+  <symbol id="i-map" viewBox="0 0 16 16"><path d="M3 5h6M3 11h10"/><path d="m7 3 2 2-2 2M11 9l2 2-2 2"/></symbol>
+  <symbol id="i-apps" viewBox="0 0 16 16"><rect x="2.5" y="2.5" width="4.5" height="4.5" rx="1"/><rect x="9" y="2.5" width="4.5" height="4.5" rx="1"/><rect x="2.5" y="9" width="4.5" height="4.5" rx="1"/><rect x="9" y="9" width="4.5" height="4.5" rx="1"/></symbol>
+  <symbol id="i-q" viewBox="0 0 16 16"><circle cx="8" cy="8" r="5.5"/><path d="M6.4 6.4a1.7 1.7 0 0 1 3.2.6c0 1.1-1.6 1.4-1.6 2.4M8 11.2v.1"/></symbol>
+  <symbol id="i-gear" viewBox="0 0 16 16"><circle cx="8" cy="8" r="2"/><path d="M8 2.2v1.6M8 12.2v1.6M2.2 8h1.6M12.2 8h1.6M3.9 3.9l1.1 1.1M11 11l1.1 1.1M3.9 12.1 5 11M11 5l1.1-1.1"/></symbol>
+  <symbol id="i-search" viewBox="0 0 16 16"><circle cx="7" cy="7" r="4.3"/><path d="m10.3 10.3 3.2 3.2"/></symbol>
+  <symbol id="i-plus" viewBox="0 0 16 16"><path d="M8 3.2v9.6M3.2 8h9.6"/></symbol>
+</svg>
+
+<div class="app">
+  <aside class="side">
+    <div class="logo"><svg viewBox="0 0 22 22" aria-hidden="true"><circle cx="11" cy="11" r="9" fill="none" stroke="currentColor" stroke-width="1.6"/><path d="M5.5 13.5c2-3.4 4-5 5.5-5s3.5 1.6 5.5 5" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"/></svg>ProcessLens</div>
+    <div class="navs">
+      <nav class="nav">
+        <a class="on" href="#"><svg class="i"><use href="#i-home"/></svg>Home</a>
+        <a href="#"><svg class="i"><use href="#i-help"/></svg>Needs help<span class="n">3</span></a>
+      </nav>
+      <div class="grp">Automate</div>
+      <nav class="nav">
+        <a href="#"><svg class="i"><use href="#i-tasks"/></svg>Tasks</a>
+        <a href="#"><svg class="i"><use href="#i-hist"/></svg>Runs</a>
+      </nav>
+      <div class="grp">Your data</div>
+      <nav class="nav">
+        <a href="#"><svg class="i"><use href="#i-sheet"/></svg>Spreadsheets</a>
+        <a href="#"><svg class="i"><use href="#i-doc"/></svg>Documents</a>
+        <a href="#"><svg class="i"><use href="#i-map"/></svg>Saved answers</a>
+      </nav>
+      <div class="grp">Connect</div>
+      <nav class="nav">
+        <a href="#"><svg class="i"><use href="#i-apps"/></svg>Apps</a>
+      </nav>
+    </div>
+    <div class="side-foot">
+      <nav class="nav"><a href="#"><svg class="i"><use href="#i-gear"/></svg>Settings</a><a href="#"><svg class="i"><use href="#i-q"/></svg>Help</a></nav>
+      <div class="ext"><i></i>Chrome connected</div>
+    </div>
+  </aside>
+
+  <main>
+    <div class="head in" style="--i:0">
+      <h2>Home</h2>
+      <div class="search"><svg class="i"><use href="#i-search"/></svg>Search<kbd>Ctrl K</kbd></div>
+      <a class="btn primary" href="#"><svg class="i"><use href="#i-plus"/></svg>Teach a new task</a>
+      <span class="avatar">JV</span>
+    </div>
+
+    <section class="hero">
+      <div>
+        <h1 class="big in" style="--i:1">412 rows done this week.<br><span>3 need you.</span></h1>
+        <p class="lede in" style="--i:2">Nothing was entered twice.</p>
+      </div>
+      <div class="saved-fig in" style="--i:2">
+        <b>6 h 12 m</b>
+        <span>Time saved this week</span>
+        <small>vs. about 3 minutes a row by hand</small>
+      </div>
+    </section>
+
+    <section class="two">
+      <div class="panel in" style="--i:3">
+        <div class="panel-h"><h3>Needs your help</h3><a href="#">See all</a></div>
+        <ul class="rows">
+          <li><div><b>Priya Nair</b><p>The salesperson “R. Iyer” isn't in Odoo.</p></div><button class="btn quiet">Choose salesperson</button></li>
+          <li><div><b>Invoice INV-2041</b><p>The total doesn't match its items.</p></div><button class="btn quiet">Check invoice</button></li>
+          <li><div><b>SKU-88120</b><p>The new price is negative.</p></div><button class="btn quiet">Fix row</button></li>
+        </ul>
+      </div>
+      <div class="panel in" style="--i:4">
+        <div class="panel-h"><h3>Running now</h3><span class="live"><i></i>Live</span></div>
+        <div class="run">
+          <b>Add customer inquiries to Odoo CRM</b>
+          <div class="track" aria-hidden="true"><i id="bar"></i></div>
+          <div class="meta"><span><span id="done">11</span> of 20 done</span><span><span id="already">2</span> already there</span></div>
+        </div>
+      </div>
+    </section>
+
+    <section class="panel in" style="--i:5">
+      <div class="panel-h"><h3>My tasks</h3><a href="#">See all</a></div>
+      <table>
+        <thead><tr><th>Task</th><th>Last run</th><th>Result</th><th></th></tr></thead>
+        <tbody>
+          <tr><td><b>Add customer inquiries</b><small>Odoo CRM</small></td><td>Now</td><td><span class="res live">Running</span></td><td class="act"><button class="btn quiet">Open</button></td></tr>
+          <tr><td><b>Update product prices</b><small>Odoo Inventory</small></td><td>2 hours ago</td><td><span class="res help">1 needs help</span></td><td class="act"><button class="btn quiet">Run again</button></td></tr>
+          <tr><td><b>Enroll students in courses</b><small>Odoo Contacts</small></td><td>Yesterday</td><td><span class="res ok">All done</span></td><td class="act"><button class="btn quiet">Run again</button></td></tr>
+          <tr><td><b>Add leads</b><small>Twenty</small></td><td>Never</td><td><span class="res idle">Ready</span></td><td class="act"><button class="btn quiet">Try one row</button></td></tr>
+        </tbody>
+      </table>
+    </section>
+  </main>
+</div>
+
+<script>
+(() => {
+  let done = 11, already = 2, n = 0;
+  const paint = () => {
+    document.getElementById("bar").style.width = (done / 20 * 100) + "%";
+    document.getElementById("done").textContent = done;
+    document.getElementById("already").textContent = already;
+  };
+  paint();
+  if (matchMedia("(prefers-reduced-motion: reduce)").matches) return;
+  setInterval(() => { if (done >= 20) return; done++; if (n++ % 5 === 3) already++; paint(); }, 3200);
+})();
+</script>

From 6d6148f16b94e301e2dd84511a75fe6ed97229f0 Mon Sep 17 00:00:00 2001
From: Jayanth Vasupilli <156448548+jayanthvee@users.noreply.github.com>
Date: Thu, 15 Oct 2026 16:03:43 -0700
Subject: [PATCH 02/12] feat(web): rebuild apps/web in React with the approved
 shell, tokens and router

The PL-015 plain page becomes a React 18 + TypeScript app built by Vite, in the look of internal/docs/design/home-mock.html: its CSS tokens, the fog background, the frosted sidebar of four places plus Settings, Help and the Chrome status, the header with Ctrl K search and one primary action, and the blur-in motion that only runs on a page's first render.

The shell serves the built page: a client-side route answers index.html so a refresh on /runs/abc does not 404, while a missing asset still does. GET /api/v1/executor/session reads the hub's own session registry for the sidebar's status line, changing no frame, socket or token check.
---
 apps/web/index.html                 |  11 +-
 apps/web/package-lock.json          | 461 ++++++++++++++++++++++++----
 apps/web/package.json               |  23 +-
 apps/web/src/App.tsx                |  40 +++
 apps/web/src/api.ts                 | 105 -------
 apps/web/src/app.ts                 | 394 ------------------------
 apps/web/src/lib/api.ts             |  87 ++++++
 apps/web/src/lib/useJson.ts         |  64 ++++
 apps/web/src/lib/words.ts           | 163 ++++++++++
 apps/web/src/logic.ts               | 359 ----------------------
 apps/web/src/main.ts                |  10 -
 apps/web/src/main.tsx               |  31 ++
 apps/web/src/pages/ComingSoon.tsx   |  24 ++
 apps/web/src/pages/Home.tsx         |   6 +
 apps/web/src/pages/NeedsHelp.tsx    |   6 +
 apps/web/src/pages/RunDetail.tsx    |   6 +
 apps/web/src/pages/Runs.tsx         |   6 +
 apps/web/src/pages/TaskDetail.tsx   |   6 +
 apps/web/src/pages/Tasks.tsx        |   6 +
 apps/web/src/shell/EmptyState.tsx   |  18 ++
 apps/web/src/shell/Header.tsx       |  26 ++
 apps/web/src/shell/Icons.tsx        |  86 ++++++
 apps/web/src/shell/Search.tsx       |  77 +++++
 apps/web/src/shell/Shell.tsx        |  64 ++++
 apps/web/src/shell/Sidebar.tsx      | 110 +++++++
 apps/web/src/shell/shell.css        |  56 ++++
 apps/web/src/styles.css             | 126 --------
 apps/web/src/styles/global.css      |  87 ++++++
 apps/web/src/styles/tokens.css      |  12 +
 apps/web/src/types.ts               | 121 ++++++--
 apps/web/src/view.ts                | 382 -----------------------
 apps/web/tests/api.test.ts          | 108 +++++++
 apps/web/tests/commitGate.test.ts   | 193 ------------
 apps/web/tests/errorDetail.test.ts  | 150 ---------
 apps/web/tests/helpers.ts           | 138 ---------
 apps/web/tests/helpers.tsx          | 114 +++++++
 apps/web/tests/injection.test.ts    | 101 ------
 apps/web/tests/polling.test.ts      | 116 -------
 apps/web/tests/router.test.tsx      |  84 +++++
 apps/web/tests/runButtons.test.ts   |  94 ------
 apps/web/tests/shell.test.tsx       | 122 ++++++++
 apps/web/tests/words.test.ts        | 184 +++++++++++
 apps/web/tsconfig.json              |   1 +
 apps/web/vite.config.ts             |  11 +-
 services/api/hub.py                 |  17 +
 services/api/main.py                |  29 +-
 tests/api/test_hub_session_state.py |  85 +++++
 tests/api/test_web_serving.py       |  39 +++
 48 files changed, 2276 insertions(+), 2283 deletions(-)
 create mode 100644 apps/web/src/App.tsx
 delete mode 100644 apps/web/src/api.ts
 delete mode 100644 apps/web/src/app.ts
 create mode 100644 apps/web/src/lib/api.ts
 create mode 100644 apps/web/src/lib/useJson.ts
 create mode 100644 apps/web/src/lib/words.ts
 delete mode 100644 apps/web/src/logic.ts
 delete mode 100644 apps/web/src/main.ts
 create mode 100644 apps/web/src/main.tsx
 create mode 100644 apps/web/src/pages/ComingSoon.tsx
 create mode 100644 apps/web/src/pages/Home.tsx
 create mode 100644 apps/web/src/pages/NeedsHelp.tsx
 create mode 100644 apps/web/src/pages/RunDetail.tsx
 create mode 100644 apps/web/src/pages/Runs.tsx
 create mode 100644 apps/web/src/pages/TaskDetail.tsx
 create mode 100644 apps/web/src/pages/Tasks.tsx
 create mode 100644 apps/web/src/shell/EmptyState.tsx
 create mode 100644 apps/web/src/shell/Header.tsx
 create mode 100644 apps/web/src/shell/Icons.tsx
 create mode 100644 apps/web/src/shell/Search.tsx
 create mode 100644 apps/web/src/shell/Shell.tsx
 create mode 100644 apps/web/src/shell/Sidebar.tsx
 create mode 100644 apps/web/src/shell/shell.css
 delete mode 100644 apps/web/src/styles.css
 create mode 100644 apps/web/src/styles/global.css
 create mode 100644 apps/web/src/styles/tokens.css
 delete mode 100644 apps/web/src/view.ts
 create mode 100644 apps/web/tests/api.test.ts
 delete mode 100644 apps/web/tests/commitGate.test.ts
 delete mode 100644 apps/web/tests/errorDetail.test.ts
 delete mode 100644 apps/web/tests/helpers.ts
 create mode 100644 apps/web/tests/helpers.tsx
 delete mode 100644 apps/web/tests/injection.test.ts
 delete mode 100644 apps/web/tests/polling.test.ts
 create mode 100644 apps/web/tests/router.test.tsx
 delete mode 100644 apps/web/tests/runButtons.test.ts
 create mode 100644 apps/web/tests/shell.test.tsx
 create mode 100644 apps/web/tests/words.test.ts
 create mode 100644 tests/api/test_hub_session_state.py
 create mode 100644 tests/api/test_web_serving.py

diff --git a/apps/web/index.html b/apps/web/index.html
index 3963c20..09ca2f8 100644
--- a/apps/web/index.html
+++ b/apps/web/index.html
@@ -3,14 +3,11 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>ProcessLens — runs</title>
+    <meta name="color-scheme" content="light" />
+    <title>ProcessLens</title>
   </head>
   <body>
-    <header class="topbar">
-      <h1>ProcessLens</h1>
-      <nav><a href="#/">Runs</a></nav>
-    </header>
-    <main id="app"></main>
-    <script type="module" src="/src/main.ts"></script>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
   </body>
 </html>
diff --git a/apps/web/package-lock.json b/apps/web/package-lock.json
index 9533983..e43b16d 100644
--- a/apps/web/package-lock.json
+++ b/apps/web/package-lock.json
@@ -7,12 +7,69 @@
     "": {
       "name": "process-lens-web",
       "version": "0.1.0",
+      "dependencies": {
+        "@fontsource/public-sans": "5.3.0",
+        "react": "18.3.1",
+        "react-dom": "18.3.1",
+        "react-router-dom": "6.30.6"
+      },
       "devDependencies": {
-        "@types/node": "^22.10.0",
-        "happy-dom": "^20.0.0",
-        "typescript": "^5.6.3",
-        "vite": "^8.3.4",
-        "vitest": "^4.1.11"
+        "@testing-library/react": "16.3.3",
+        "@testing-library/user-event": "14.6.8",
+        "@types/node": "22.20.5",
+        "@types/react": "18.3.31",
+        "@types/react-dom": "18.3.7",
+        "@vitejs/plugin-react": "6.0.0",
+        "happy-dom": "20.0.0",
+        "typescript": "5.6.3",
+        "vite": "8.3.4",
+        "vitest": "4.1.11"
+      }
+    },
+    "node_modules/@babel/code-frame": {
+      "version": "7.29.7",
+      "resolved": "https://registry.npmjs.org/@babel/code-frame/-/code-frame-7.29.7.tgz",
+      "integrity": "sha512-Aup7aUOfpbAUg2ROOJN6Iw5f9DMBlzu0mIkm/malLQFN/YQgO48wCj0Kxa3sEHJvPVFg7siR+qRInwXd2qhQKw==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "@babel/helper-validator-identifier": "^7.29.7",
+        "js-tokens": "^4.0.0",
+        "picocolors": "^1.1.1"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/helper-validator-identifier": {
+      "version": "7.29.7",
+      "resolved": "https://registry.npmjs.org/@babel/helper-validator-identifier/-/helper-validator-identifier-7.29.7.tgz",
+      "integrity": "sha512-qehxGkRj55h/ff8EMaJ+cYhyaKlHIxqYDn682wQD7RNp9UujOQsHog2uS0r2vzr4pW+sXf90NeeayjcNaX3fFg==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true,
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/runtime": {
+      "version": "7.29.10",
+      "resolved": "https://registry.npmjs.org/@babel/runtime/-/runtime-7.29.10.tgz",
+      "integrity": "sha512-NpugTzbKgGrNe45Ui32cN8vCFFMxVtP/9rtfwv0nP5FRDAjvYBxJcLVpYA9mr1jxP6cnIT7x9LUzuDTbWYYNRA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@fontsource/public-sans": {
+      "version": "5.3.0",
+      "resolved": "https://registry.npmjs.org/@fontsource/public-sans/-/public-sans-5.3.0.tgz",
+      "integrity": "sha512-kjODI0S3zdv0mBYCIQ8TbBayaiqszpc2UbhJiO3bjIqVVXzcWfHSt2o3WBCLOY3juaGaQoy4MoWCcgmfI5hCuA==",
+      "license": "OFL-1.1",
+      "funding": {
+        "url": "https://github.com/sponsors/ayuhito"
       }
     },
     "node_modules/@jridgewell/sourcemap-codec": {
@@ -32,6 +89,15 @@
         "url": "https://github.com/sponsors/oxc-project"
       }
     },
+    "node_modules/@remix-run/router": {
+      "version": "1.23.4",
+      "resolved": "https://registry.npmjs.org/@remix-run/router/-/router-1.23.4.tgz",
+      "integrity": "sha512-q7j5geK7xs3UJSdm9/iytUNclBnLmYx1EnSeCFXHPeutdqgIMeFeHtUZgS3EhlKxdBEAu8OwtJCwmLrEzpSs7Q==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=14.0.0"
+      }
+    },
     "node_modules/@rolldown/binding-android-arm-eabi": {
       "version": "1.2.13",
       "resolved": "https://registry.npmjs.org/@rolldown/binding-android-arm-eabi/-/binding-android-arm-eabi-1.2.13.tgz",
@@ -319,6 +385,77 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/@testing-library/dom": {
+      "version": "10.4.2",
+      "resolved": "https://registry.npmjs.org/@testing-library/dom/-/dom-10.4.2.tgz",
+      "integrity": "sha512-yzr2S9HyAIdhz2/6qHgbs665Q7PKVcDF05vsOlHPxG1mo36gKVesdYVeDLnXgfjJ03CrKRk08knc6+E/9m8v2Q==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "@babel/code-frame": "^7.10.4",
+        "@babel/runtime": "^7.12.5",
+        "@types/aria-query": "^5.0.1",
+        "aria-query": "5.3.0",
+        "dom-accessibility-api": "^0.5.9",
+        "lz-string": "^1.5.0",
+        "picocolors": "1.1.1",
+        "pretty-format": "^27.0.2"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@testing-library/react": {
+      "version": "16.3.3",
+      "resolved": "https://registry.npmjs.org/@testing-library/react/-/react-16.3.3.tgz",
+      "integrity": "sha512-Uo193NgQbPMz6lrrhtRQQFcMC6Re/ELLFbbuVL30WDlZxlpZf9/lMHTAVxPRLw1q1iu9OJmR1c2BLiENRstdBg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/runtime": "^7.12.5"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "peerDependencies": {
+        "@testing-library/dom": "^10.0.0",
+        "@types/react": "^18.0.0 || ^19.0.0",
+        "@types/react-dom": "^18.0.0 || ^19.0.0",
+        "react": "^18.0.0 || ^19.0.0",
+        "react-dom": "^18.0.0 || ^19.0.0"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        },
+        "@types/react-dom": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@testing-library/user-event": {
+      "version": "14.6.8",
+      "resolved": "https://registry.npmjs.org/@testing-library/user-event/-/user-event-14.6.8.tgz",
+      "integrity": "sha512-vgSSqnANMnkcYR/vUNDbwS7aM3OErRLNUG8vCVVlj4oc6cKffUrccX7UAS5AmJQQNZTSibi9z5GvvRZ0aYgUCQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12",
+        "npm": ">=6"
+      },
+      "peerDependencies": {
+        "@testing-library/dom": ">=7.21.4"
+      }
+    },
+    "node_modules/@types/aria-query": {
+      "version": "5.0.4",
+      "resolved": "https://registry.npmjs.org/@types/aria-query/-/aria-query-5.0.4.tgz",
+      "integrity": "sha512-rfT93uj5s0PRL7EzccGMs3brplhcrghnDoV26NqKhCAS1hVo+WdNsPvE/yb6ilfr5hi2MEk6d5EWJTKdxg8jVw==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true
+    },
     "node_modules/@types/chai": {
       "version": "5.2.3",
       "resolved": "https://registry.npmjs.org/@types/chai/-/chai-5.2.3.tgz",
@@ -354,6 +491,34 @@
         "undici-types": "~6.21.0"
       }
     },
+    "node_modules/@types/prop-types": {
+      "version": "15.7.15",
+      "resolved": "https://registry.npmjs.org/@types/prop-types/-/prop-types-15.7.15.tgz",
+      "integrity": "sha512-F6bEyamV9jKGAFBEmlQnesRPGOQqS2+Uwi0Em15xenOxHaf2hv6L8YCVn3rPdPJOiJfPiCnLIRyvwVaqMY3MIw==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@types/react": {
+      "version": "18.3.31",
+      "resolved": "https://registry.npmjs.org/@types/react/-/react-18.3.31.tgz",
+      "integrity": "sha512-vfEqpXTvwT91yhmwdfouStN2hSKwTvyRs8qpLfADyrq/kxDw0hZM7Wk9Ug1FELj8hIby+S/+kQCSRFF32nv2Qw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/prop-types": "*",
+        "csstype": "^3.2.2"
+      }
+    },
+    "node_modules/@types/react-dom": {
+      "version": "18.3.7",
+      "resolved": "https://registry.npmjs.org/@types/react-dom/-/react-dom-18.3.7.tgz",
+      "integrity": "sha512-MEe3UeoENYVFXzoXEWsvcpg6ZvlrFNlOQ7EOsvhI3CfAXwzPfO8Qwuxd40nepsYKqyyVQnTdEfv68q91yLcKrQ==",
+      "dev": true,
+      "license": "MIT",
+      "peerDependencies": {
+        "@types/react": "^18.0.0"
+      }
+    },
     "node_modules/@types/whatwg-mimetype": {
       "version": "3.0.2",
       "resolved": "https://registry.npmjs.org/@types/whatwg-mimetype/-/whatwg-mimetype-3.0.2.tgz",
@@ -361,16 +526,39 @@
       "dev": true,
       "license": "MIT"
     },
-    "node_modules/@types/ws": {
-      "version": "8.18.2",
-      "resolved": "https://registry.npmjs.org/@types/ws/-/ws-8.18.2.tgz",
-      "integrity": "sha512-67MQl+fpWKVTT1NYdnmo3U4sc/xPo/zQBncVnI74qmQa0z/b+1g6iYqNmGCPbxO+zz2aklb08a0oHfegiVd0/w==",
+    "node_modules/@vitejs/plugin-react": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/@vitejs/plugin-react/-/plugin-react-6.0.0.tgz",
+      "integrity": "sha512-Bu5/eP6td3WI654+tRq+ryW1PbgA90y5pqMKpb3U7UpNk6VjI53P/ncPUd192U9dSrepLy7DHnq1XEMDz5H++w==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@types/node": "*"
+        "@rolldown/pluginutils": "1.0.0-rc.7"
+      },
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      },
+      "peerDependencies": {
+        "@rolldown/plugin-babel": "^0.1.7",
+        "babel-plugin-react-compiler": "^1.0.0",
+        "vite": "^8.0.0"
+      },
+      "peerDependenciesMeta": {
+        "@rolldown/plugin-babel": {
+          "optional": true
+        },
+        "babel-plugin-react-compiler": {
+          "optional": true
+        }
       }
     },
+    "node_modules/@vitejs/plugin-react/node_modules/@rolldown/pluginutils": {
+      "version": "1.0.0-rc.7",
+      "resolved": "https://registry.npmjs.org/@rolldown/pluginutils/-/pluginutils-1.0.0-rc.7.tgz",
+      "integrity": "sha512-qujRfC8sFVInYSPPMLQByRh7zhwkGFS4+tyMQ83srV1qrxL4g8E2tyxVVyxd0+8QeBM1mIk9KbWxkegRr76XzA==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@vitest/expect": {
       "version": "4.1.11",
       "resolved": "https://registry.npmjs.org/@vitest/expect/-/expect-4.1.11.tgz",
@@ -484,27 +672,50 @@
         "url": "https://opencollective.com/vitest"
       }
     },
-    "node_modules/assertion-error": {
-      "version": "2.0.1",
-      "resolved": "https://registry.npmjs.org/assertion-error/-/assertion-error-2.0.1.tgz",
-      "integrity": "sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==",
+    "node_modules/ansi-regex": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz",
+      "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "engines": {
-        "node": ">=12"
+        "node": ">=8"
       }
     },
-    "node_modules/buffer-image-size": {
-      "version": "0.6.4",
-      "resolved": "https://registry.npmjs.org/buffer-image-size/-/buffer-image-size-0.6.4.tgz",
-      "integrity": "sha512-nEh+kZOPY1w+gcCMobZ6ETUp9WfibndnosbpwB1iJk/8Gt5ZF2bhS6+B6bPYz424KtwsR6Rflc3tCz1/ghX2dQ==",
+    "node_modules/ansi-styles": {
+      "version": "5.2.0",
+      "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-5.2.0.tgz",
+      "integrity": "sha512-Cxwpt2SfTzTtXcfOlzGEee8O+c+MmUgGrNiBcXnuWxuFJHe6a5Hz7qwhwe5OgaSYI0IJvkLqWX1ASG+cJOkEiA==",
       "dev": true,
       "license": "MIT",
-      "dependencies": {
-        "@types/node": "*"
+      "peer": true,
+      "engines": {
+        "node": ">=10"
       },
+      "funding": {
+        "url": "https://github.com/chalk/ansi-styles?sponsor=1"
+      }
+    },
+    "node_modules/aria-query": {
+      "version": "5.3.0",
+      "resolved": "https://registry.npmjs.org/aria-query/-/aria-query-5.3.0.tgz",
+      "integrity": "sha512-b0P0sZPKtyu8HkeRAfCq0IfURZK+SuwMjY1UXGBU27wpAiTwQAIlq56IbIO+ytk/JjS1fMR14ee5WBBfKi5J6A==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "peer": true,
+      "dependencies": {
+        "dequal": "^2.0.3"
+      }
+    },
+    "node_modules/assertion-error": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/assertion-error/-/assertion-error-2.0.1.tgz",
+      "integrity": "sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==",
+      "dev": true,
+      "license": "MIT",
       "engines": {
-        "node": ">=4.0"
+        "node": ">=12"
       }
     },
     "node_modules/chai": {
@@ -524,6 +735,24 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/csstype": {
+      "version": "3.2.3",
+      "resolved": "https://registry.npmjs.org/csstype/-/csstype-3.2.3.tgz",
+      "integrity": "sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/dequal": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/dequal/-/dequal-2.0.3.tgz",
+      "integrity": "sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true,
+      "engines": {
+        "node": ">=6"
+      }
+    },
     "node_modules/detect-libc": {
       "version": "2.1.2",
       "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz",
@@ -534,18 +763,13 @@
         "node": ">=8"
       }
     },
-    "node_modules/entities": {
-      "version": "7.0.1",
-      "resolved": "https://registry.npmjs.org/entities/-/entities-7.0.1.tgz",
-      "integrity": "sha512-TWrgLOFUQTH994YUyl1yT4uyavY5nNB5muff+RtWaqNVCAK408b5ZnnbNAUEWLTCpum9w6arT70i1XdQ4UeOPA==",
+    "node_modules/dom-accessibility-api": {
+      "version": "0.5.16",
+      "resolved": "https://registry.npmjs.org/dom-accessibility-api/-/dom-accessibility-api-0.5.16.tgz",
+      "integrity": "sha512-X7BJ2yElsnOJ30pZF4uIIDfBEVgF4XEBxL9Bxhy6dnrm5hkzqmsWHGTiHqRiITNhMyFLyAiWndIJP7Z1NTteDg==",
       "dev": true,
-      "license": "BSD-2-Clause",
-      "engines": {
-        "node": ">=0.12"
-      },
-      "funding": {
-        "url": "https://github.com/fb55/entities?sponsor=1"
-      }
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/es-module-lexer": {
       "version": "2.3.2",
@@ -608,24 +832,36 @@
       }
     },
     "node_modules/happy-dom": {
-      "version": "20.14.6",
-      "resolved": "https://registry.npmjs.org/happy-dom/-/happy-dom-20.14.6.tgz",
-      "integrity": "sha512-5DDsf4QmEIlRL6NkCv/fxSjYHHkZceL/IaYQdJc2h3G7DRTEai++VTjbfL0LB9geW2VrA3+vrjF3Efx+OTtX0Q==",
+      "version": "20.0.0",
+      "resolved": "https://registry.npmjs.org/happy-dom/-/happy-dom-20.0.0.tgz",
+      "integrity": "sha512-GkWnwIFxVGCf2raNrxImLo397RdGhLapj5cT3R2PT7FwL62Ze1DROhzmYW7+J3p9105DYMVenEejEbnq5wA37w==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@types/node": ">=20.0.0",
+        "@types/node": "^20.0.0",
         "@types/whatwg-mimetype": "^3.0.2",
-        "@types/ws": "^8.18.1",
-        "buffer-image-size": "^0.6.4",
-        "entities": "^7.0.1",
-        "whatwg-mimetype": "^3.0.0",
-        "ws": "^8.21.0"
+        "whatwg-mimetype": "^3.0.0"
       },
       "engines": {
         "node": ">=20.0.0"
       }
     },
+    "node_modules/happy-dom/node_modules/@types/node": {
+      "version": "20.19.43",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-20.19.43.tgz",
+      "integrity": "sha512-6oYBAi5ikg4Pl+kGsoYtawUMBT2zZMCvPNF7pVLnHZfd1zf38DRiWn/gT01RYCdUqkv7Fhr+C9ot4/tb+2sVvA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "undici-types": "~6.21.0"
+      }
+    },
+    "node_modules/js-tokens": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz",
+      "integrity": "sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==",
+      "license": "MIT"
+    },
     "node_modules/lightningcss": {
       "version": "1.33.0",
       "resolved": "https://registry.npmjs.org/lightningcss/-/lightningcss-1.33.0.tgz",
@@ -899,6 +1135,29 @@
         "url": "https://opencollective.com/parcel"
       }
     },
+    "node_modules/loose-envify": {
+      "version": "1.4.0",
+      "resolved": "https://registry.npmjs.org/loose-envify/-/loose-envify-1.4.0.tgz",
+      "integrity": "sha512-lyuxPGr/Wfhrlem2CL/UcnUc1zcqKAImBDzukY7Y5F/yQiNdko6+fRLevlw1HgMySw7f611UIY408EtxRSoK3Q==",
+      "license": "MIT",
+      "dependencies": {
+        "js-tokens": "^3.0.0 || ^4.0.0"
+      },
+      "bin": {
+        "loose-envify": "cli.js"
+      }
+    },
+    "node_modules/lz-string": {
+      "version": "1.5.0",
+      "resolved": "https://registry.npmjs.org/lz-string/-/lz-string-1.5.0.tgz",
+      "integrity": "sha512-h5bgJWpxJNswbU7qCrV0tIKQCaS3blPDrqKWx+QxzuzL1zGUzij9XCWLrSLsJPu5t+eWA/ycetzYAO5IOMcWAQ==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true,
+      "bin": {
+        "lz-string": "bin/bin.js"
+      }
+    },
     "node_modules/magic-string": {
       "version": "0.30.21",
       "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.30.21.tgz",
@@ -998,6 +1257,87 @@
         "node": "^10 || ^12 || >=14"
       }
     },
+    "node_modules/pretty-format": {
+      "version": "27.5.1",
+      "resolved": "https://registry.npmjs.org/pretty-format/-/pretty-format-27.5.1.tgz",
+      "integrity": "sha512-Qb1gy5OrP5+zDf2Bvnzdl3jsTf1qXVMazbvCoKhtKqVs4/YK4ozX4gKQJJVyNe+cajNPn0KoC0MC3FUmaHWEmQ==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "ansi-regex": "^5.0.1",
+        "ansi-styles": "^5.0.0",
+        "react-is": "^17.0.1"
+      },
+      "engines": {
+        "node": "^10.13.0 || ^12.13.0 || ^14.15.0 || >=15.0.0"
+      }
+    },
+    "node_modules/react": {
+      "version": "18.3.1",
+      "resolved": "https://registry.npmjs.org/react/-/react-18.3.1.tgz",
+      "integrity": "sha512-wS+hAgJShR0KhEvPJArfuPVN1+Hz1t0Y6n5jLrGQbkb4urgPE/0Rve+1kMB1v/oWgHgm4WIcV+i7F2pTVj+2iQ==",
+      "license": "MIT",
+      "dependencies": {
+        "loose-envify": "^1.1.0"
+      },
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/react-dom": {
+      "version": "18.3.1",
+      "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-18.3.1.tgz",
+      "integrity": "sha512-5m4nQKp+rZRb09LNH59GM4BxTh9251/ylbKIbpe7TpGxfJ+9kv6BLkLBXIjjspbgbnIBNqlI23tRnTWT0snUIw==",
+      "license": "MIT",
+      "dependencies": {
+        "loose-envify": "^1.1.0",
+        "scheduler": "^0.23.2"
+      },
+      "peerDependencies": {
+        "react": "^18.3.1"
+      }
+    },
+    "node_modules/react-is": {
+      "version": "17.0.2",
+      "resolved": "https://registry.npmjs.org/react-is/-/react-is-17.0.2.tgz",
+      "integrity": "sha512-w2GsyukL62IJnlaff/nRegPQR94C/XXamvMWmSHRJ4y7Ts/4ocGRmTHvOs8PSE6pB3dWOrD/nueuU5sduBsQ4w==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true
+    },
+    "node_modules/react-router": {
+      "version": "6.30.6",
+      "resolved": "https://registry.npmjs.org/react-router/-/react-router-6.30.6.tgz",
+      "integrity": "sha512-5HfK7k5im7LTOB0EqCQmfvy4C13G92Ssj1VTmouTK3AJvyjKTnFuCV0vcMAD/JS+JC4DvDIBRrlAeJIFjh5VWg==",
+      "license": "MIT",
+      "dependencies": {
+        "@remix-run/router": "1.23.4"
+      },
+      "engines": {
+        "node": ">=14.0.0"
+      },
+      "peerDependencies": {
+        "react": ">=16.8"
+      }
+    },
+    "node_modules/react-router-dom": {
+      "version": "6.30.6",
+      "resolved": "https://registry.npmjs.org/react-router-dom/-/react-router-dom-6.30.6.tgz",
+      "integrity": "sha512-0RHKZz7wwffvkU+2MFVT2NnjK44ssLEV+m0CAJaS2Ksmorrwj7WxH00jO0SOCW26/tINUnJHToXblDs33I38YQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@remix-run/router": "1.23.4",
+        "react-router": "6.30.6"
+      },
+      "engines": {
+        "node": ">=14.0.0"
+      },
+      "peerDependencies": {
+        "react": ">=16.8",
+        "react-dom": ">=16.8"
+      }
+    },
     "node_modules/rolldown": {
       "version": "1.2.13",
       "resolved": "https://registry.npmjs.org/rolldown/-/rolldown-1.2.13.tgz",
@@ -1032,6 +1372,15 @@
         "@rolldown/binding-win32-x64-msvc": "1.2.13"
       }
     },
+    "node_modules/scheduler": {
+      "version": "0.23.2",
+      "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.23.2.tgz",
+      "integrity": "sha512-UOShsPwz7NrMUqhR6t0hWjFduvOzbtv7toDH1/hIrfRNIDBnnBWd0CwJTGvTpngVlmwGCdP9/Zl/tVrDqcuYzQ==",
+      "license": "MIT",
+      "dependencies": {
+        "loose-envify": "^1.1.0"
+      }
+    },
     "node_modules/siginfo": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/siginfo/-/siginfo-2.0.0.tgz",
@@ -1108,9 +1457,9 @@
       }
     },
     "node_modules/typescript": {
-      "version": "5.9.3",
-      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
-      "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
+      "version": "5.6.3",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.6.3.tgz",
+      "integrity": "sha512-hjcS1mhfuyi4WW8IWtjP7brDrG2cuDZukyrYrSauoXGNgx0S7zceP07adYkJycEr56BOUTNPzbInooiN3fn1qw==",
       "dev": true,
       "license": "Apache-2.0",
       "bin": {
@@ -1322,28 +1671,6 @@
       "engines": {
         "node": ">=8"
       }
-    },
-    "node_modules/ws": {
-      "version": "8.22.0",
-      "resolved": "https://registry.npmjs.org/ws/-/ws-8.22.0.tgz",
-      "integrity": "sha512-Ydggc987+RO0AnWtZ/7Wq9FtNvcrL1b/RO0ud9mWjUPgDrsAAwQSF51sm2hm1XofbU/4jkpGEsLFsZZxU+1DOg==",
-      "dev": true,
-      "license": "MIT",
-      "engines": {
-        "node": ">=10.0.0"
-      },
-      "peerDependencies": {
-        "bufferutil": "^4.0.1",
-        "utf-8-validate": ">=5.0.2"
-      },
-      "peerDependenciesMeta": {
-        "bufferutil": {
-          "optional": true
-        },
-        "utf-8-validate": {
-          "optional": true
-        }
-      }
     }
   }
 }
diff --git a/apps/web/package.json b/apps/web/package.json
index 7fdadd5..b53eb11 100644
--- a/apps/web/package.json
+++ b/apps/web/package.json
@@ -2,7 +2,7 @@
   "name": "process-lens-web",
   "version": "0.1.0",
   "private": true,
-  "description": "The local operator page for ProcessLens runs.",
+  "description": "The ProcessLens web app: Home, Tasks, Runs and Needs help.",
   "type": "module",
   "scripts": {
     "dev": "vite",
@@ -11,11 +11,22 @@
     "test": "vitest run",
     "check": "npm run typecheck && npm run test && npm run build"
   },
+  "dependencies": {
+    "@fontsource/public-sans": "5.3.0",
+    "react": "18.3.1",
+    "react-dom": "18.3.1",
+    "react-router-dom": "6.30.6"
+  },
   "devDependencies": {
-    "@types/node": "^22.10.0",
-    "happy-dom": "^20.0.0",
-    "typescript": "^5.6.3",
-    "vite": "^8.3.4",
-    "vitest": "^4.1.11"
+    "@testing-library/react": "16.3.3",
+    "@testing-library/user-event": "14.6.8",
+    "@types/node": "22.20.5",
+    "@types/react": "18.3.31",
+    "@types/react-dom": "18.3.7",
+    "@vitejs/plugin-react": "6.0.0",
+    "happy-dom": "20.0.0",
+    "typescript": "5.6.3",
+    "vite": "8.3.4",
+    "vitest": "4.1.11"
   }
 }
diff --git a/apps/web/src/App.tsx b/apps/web/src/App.tsx
new file mode 100644
index 0000000..e681d48
--- /dev/null
+++ b/apps/web/src/App.tsx
@@ -0,0 +1,40 @@
+import { Route, Routes } from "react-router-dom";
+
+import { ComingSoon } from "./pages/ComingSoon";
+import { Home } from "./pages/Home";
+import { NeedsHelp } from "./pages/NeedsHelp";
+import { RunDetail } from "./pages/RunDetail";
+import { Runs } from "./pages/Runs";
+import { TaskDetail } from "./pages/TaskDetail";
+import { Tasks } from "./pages/Tasks";
+import { Shell } from "./shell/Shell";
+
+/**
+ * The router. Every sidebar item lands on a real page: the ones this ticket does not build show a
+ * designed empty state, so nothing is ever blank.
+ *
+ * `main.tsx` wraps this in a `BrowserRouter`; the tests wrap it in a `MemoryRouter`, which is why
+ * the router lives only here.
+ */
+export function App(): JSX.Element {
+  return (
+    <Routes>
+      <Route element={<Shell />}>
+        <Route path="/" element={<Home />} />
+        <Route path="/needs-help" element={<NeedsHelp />} />
+        <Route path="/tasks" element={<Tasks />} />
+        <Route path="/tasks/:id" element={<TaskDetail />} />
+        <Route path="/runs" element={<Runs />} />
+        <Route path="/runs/:id" element={<RunDetail />} />
+        <Route path="/teach" element={<ComingSoon />} />
+        <Route path="/spreadsheets" element={<ComingSoon />} />
+        <Route path="/documents" element={<ComingSoon />} />
+        <Route path="/saved-answers" element={<ComingSoon />} />
+        <Route path="/apps" element={<ComingSoon />} />
+        <Route path="/settings" element={<ComingSoon />} />
+        <Route path="/help" element={<ComingSoon />} />
+        <Route path="*" element={<ComingSoon />} />
+      </Route>
+    </Routes>
+  );
+}
diff --git a/apps/web/src/api.ts b/apps/web/src/api.ts
deleted file mode 100644
index 1242682..0000000
--- a/apps/web/src/api.ts
+++ /dev/null
@@ -1,105 +0,0 @@
-/**
- * The API client. Every path is relative, so the page talks to the API it was served by and never
- * to a host it made up.
- */
-
-import type { OperatorInfo } from "./types";
-
-export interface ApiSuccess<T> {
-  ok: true;
-  data: T;
-}
-
-export interface ApiFailure {
-  ok: false;
-  status: number;
-  /** The API's own `detail` text where there is one; otherwise a plain sentence. */
-  detail: string;
-}
-
-export type ApiResult<T> = ApiSuccess<T> | ApiFailure;
-
-export interface ApiClientOptions {
-  fetchImpl?: typeof fetch;
-}
-
-function errorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
-function parseJson(text: string): unknown {
-  if (text.trim() === "") return null;
-  try {
-    return JSON.parse(text);
-  } catch {
-    return null;
-  }
-}
-
-function detailFromPayload(status: number, payload: unknown): string {
-  if (payload !== null && typeof payload === "object" && "detail" in payload) {
-    const detail = (payload as { detail: unknown }).detail;
-    if (typeof detail === "string" && detail.trim() !== "") return detail;
-    if (detail !== undefined && detail !== null) return JSON.stringify(detail);
-  }
-  return `The API refused the request (HTTP ${status}).`;
-}
-
-export class ApiClient {
-  readonly #fetchImpl: typeof fetch;
-
-  constructor(options: ApiClientOptions = {}) {
-    const impl = options.fetchImpl;
-    this.#fetchImpl =
-      impl ?? ((input: RequestInfo | URL, init?: RequestInit) => fetch(input, init));
-  }
-
-  get<T>(path: string): Promise<ApiResult<T>> {
-    return this.#request<T>("GET", path);
-  }
-
-  /** A POST with no body sends no Content-Type, which is what the API's front door allows. */
-  post<T>(path: string, body?: unknown): Promise<ApiResult<T>> {
-    return this.#request<T>("POST", path, body);
-  }
-
-  async #request<T>(method: "GET" | "POST", path: string, body?: unknown): Promise<ApiResult<T>> {
-    const headers: Record<string, string> = { Accept: "application/json" };
-    const init: RequestInit = { method, headers };
-    if (body !== undefined) {
-      headers["Content-Type"] = "application/json";
-      init.body = JSON.stringify(body);
-    }
-    let response: Response;
-    try {
-      response = await this.#fetchImpl(path, init);
-    } catch (error) {
-      return { ok: false, status: 0, detail: `Could not reach the API: ${errorMessage(error)}` };
-    }
-    let text = "";
-    try {
-      text = await response.text();
-    } catch {
-      text = "";
-    }
-    const payload = parseJson(text);
-    if (response.ok !== true) {
-      return { ok: false, status: response.status, detail: detailFromPayload(response.status, payload) };
-    }
-    return { ok: true, data: payload as T };
-  }
-}
-
-/** `GET /api/v1/operator`, narrowed: 200 carries the id, 503 carries the reason. */
-export function readOperatorId(result: ApiResult<OperatorInfo>): string | null {
-  if (result.ok === false) return null;
-  const id = result.data.operator_id;
-  return typeof id === "string" && id !== "" ? id : null;
-}
-
-export function operatorProblemText(result: ApiResult<OperatorInfo>): string | null {
-  if (result.ok === true) {
-    return readOperatorId(result) === null ? "The API returned no operator id." : null;
-  }
-  return result.detail;
-}
diff --git a/apps/web/src/app.ts b/apps/web/src/app.ts
deleted file mode 100644
index faf6e08..0000000
--- a/apps/web/src/app.ts
+++ /dev/null
@@ -1,394 +0,0 @@
-/**
- * The page's wiring: read the API, keep the state, render it, and do exactly the action a person
- * clicked — never a retry of its own.
- *
- * The fetch implementation, the poll interval and the timers are all injectable, so the tests drive
- * real behaviour instead of scraping the DOM.
- */
-
-import { ApiClient, operatorProblemText, readOperatorId } from "./api";
-import * as logic from "./logic";
-import * as view from "./view";
-import type {
-  ApprovalDecision,
-  ApprovalDecisionBody,
-  ApprovalRequest,
-  OperatorInfo,
-  RecordActionBody,
-  RecordActionResponse,
-  RecordRow,
-  RunDetail,
-  RunSummary,
-  Transition,
-} from "./types";
-
-export interface MountOptions {
-  fetchImpl?: typeof fetch;
-  intervalMs?: number;
-  initialHash?: string;
-  timers?: logic.Timers;
-  listenToHashChange?: boolean;
-}
-
-export interface AppStatus {
-  route: logic.Route;
-  runId: string | null;
-  runStatus: string | null;
-  polling: boolean;
-  operatorId: string | null;
-  operatorProblem: string | null;
-}
-
-export interface AppHandle {
-  refresh: () => Promise<void>;
-  showRuns: () => Promise<void>;
-  openRun: (runId: string) => Promise<void>;
-  render: () => void;
-  status: () => AppStatus;
-  destroy: () => void;
-}
-
-interface AppState {
-  route: logic.Route;
-  operatorChecked: boolean;
-  operatorId: string | null;
-  operatorProblem: string | null;
-  runs: RunSummary[];
-  run: RunDetail | null;
-  records: RecordRow[];
-  transitions: Map<string, Transition[]>;
-  approvals: ApprovalRequest[];
-  expanded: Set<string>;
-  confirmed: Map<string, boolean>;
-  errors: Map<string, string>;
-  pageError: string | null;
-}
-
-function errorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
-export function mountApp(root: HTMLElement, options: MountOptions = {}): AppHandle {
-  const api = new ApiClient(options.fetchImpl === undefined ? {} : { fetchImpl: options.fetchImpl });
-  const intervalMs = options.intervalMs ?? logic.POLL_INTERVAL_MS;
-  const timers = options.timers ?? logic.DEFAULT_TIMERS;
-
-  const state: AppState = {
-    route: logic.routeFromHash(options.initialHash ?? ""),
-    operatorChecked: false,
-    operatorId: null,
-    operatorProblem: null,
-    runs: [],
-    run: null,
-    records: [],
-    transitions: new Map<string, Transition[]>(),
-    approvals: [],
-    expanded: new Set<string>(),
-    confirmed: new Map<string, boolean>(),
-    errors: new Map<string, string>(),
-    pageError: null,
-  };
-
-  let destroyed = false;
-
-  const poller = logic.createPoller({
-    intervalMs,
-    timers,
-    onTick: () => {
-      void refresh();
-    },
-    shouldContinue: () => state.run !== null && logic.shouldPoll(state.run.status),
-  });
-
-  function syncPoller(): void {
-    if (destroyed === false && state.run !== null && logic.shouldPoll(state.run.status)) {
-      poller.start();
-    } else {
-      poller.stop();
-    }
-  }
-
-  async function loadOperator(): Promise<void> {
-    const result = await api.get<OperatorInfo>(logic.operatorPath());
-    state.operatorChecked = true;
-    const id = readOperatorId(result);
-    if (id !== null) {
-      state.operatorId = id;
-      state.operatorProblem = null;
-      return;
-    }
-    state.operatorId = null;
-    state.operatorProblem = operatorProblemText(result) ?? logic.OPERATOR_UNAVAILABLE_MESSAGE;
-  }
-
-  async function loadRuns(): Promise<void> {
-    const result = await api.get<RunSummary[]>(logic.runsPath());
-    if (result.ok === false) {
-      state.runs = [];
-      state.pageError = result.detail;
-      return;
-    }
-    state.runs = Array.isArray(result.data) ? result.data : [];
-  }
-
-  async function loadTransitions(runId: string, reset: boolean): Promise<void> {
-    let after = 0;
-    if (reset) {
-      state.transitions.clear();
-    } else {
-      for (const list of state.transitions.values()) {
-        for (const transition of list) after = Math.max(after, transition.id);
-      }
-    }
-    const result = await api.get<Transition[]>(logic.transitionsPath(runId, after));
-    if (result.ok === false || Array.isArray(result.data) === false) return;
-    for (const transition of result.data) {
-      const existing = state.transitions.get(transition.run_record_id) ?? [];
-      existing.push(transition);
-      state.transitions.set(transition.run_record_id, existing);
-    }
-  }
-
-  async function loadRun(runId: string): Promise<void> {
-    const detail = await api.get<RunDetail>(logic.runPath(runId));
-    if (detail.ok === false) {
-      state.run = null;
-      state.records = [];
-      state.approvals = [];
-      state.pageError = detail.detail;
-      return;
-    }
-    state.run = detail.data;
-    const [records, approvals] = await Promise.all([
-      api.get<RecordRow[]>(logic.recordsPath(runId)),
-      api.get<ApprovalRequest[]>(logic.approvalsPath(runId)),
-    ]);
-    state.records = records.ok === true && Array.isArray(records.data) ? records.data : [];
-    state.approvals = approvals.ok === true && Array.isArray(approvals.data) ? approvals.data : [];
-    if (state.expanded.size > 0) await loadTransitions(runId, false);
-  }
-
-  async function refresh(): Promise<void> {
-    if (destroyed) return;
-    state.pageError = null;
-    if (state.operatorChecked === false) await loadOperator();
-    if (state.route.name === "runs") {
-      state.run = null;
-      await loadRuns();
-    } else {
-      await loadRun(state.route.id);
-    }
-    syncPoller();
-    render();
-  }
-
-  function confirmedFor(recordId: string): boolean {
-    return state.confirmed.get(recordId) === true;
-  }
-
-  async function runAction(action: logic.RunAction): Promise<void> {
-    const run = state.run;
-    if (run === null) return;
-    const key = `run:${action}`;
-    state.errors.delete(key);
-    render();
-    const result = await api.post<RunDetail>(logic.runActionPath(run.id, action));
-    if (result.ok === false) {
-      state.errors.set(key, result.detail);
-      render();
-      return;
-    }
-    await refresh();
-  }
-
-  async function recordAction(recordId: string, action: logic.RecordAction): Promise<void> {
-    const record = state.records.find((candidate) => candidate.id === recordId);
-    if (record === undefined) return;
-    const key = `${recordId}:${action}`;
-    state.errors.delete(key);
-    const gate = logic.actionGate({
-      state: record.state,
-      commitAttempted: record.commit_attempted,
-      confirmed: confirmedFor(recordId),
-      operatorId: state.operatorId,
-    });
-    if (gate.disabled) {
-      render();
-      return;
-    }
-    let body: RecordActionBody;
-    try {
-      body = logic.actionBody({
-        commitAttempted: record.commit_attempted,
-        confirmed: confirmedFor(recordId),
-        operatorId: state.operatorId,
-      });
-    } catch (error) {
-      state.errors.set(key, errorMessage(error));
-      render();
-      return;
-    }
-    const result = await api.post<RecordActionResponse>(logic.recordActionPath(recordId, action), body);
-    if (result.ok === false) {
-      state.errors.set(key, result.detail);
-      render();
-      return;
-    }
-    await refresh();
-  }
-
-  async function decide(requestId: string, decision: ApprovalDecision): Promise<void> {
-    const key = `approval:${requestId}:${decision}`;
-    state.errors.delete(key);
-    let body: ApprovalDecisionBody;
-    try {
-      body = logic.approvalBody({ requestId, decision, operatorId: state.operatorId });
-    } catch (error) {
-      state.errors.set(key, errorMessage(error));
-      render();
-      return;
-    }
-    const result = await api.post(logic.approvalDecisionPath(), body);
-    if (result.ok === false) {
-      state.errors.set(key, result.detail);
-      render();
-      return;
-    }
-    await refresh();
-  }
-
-  async function toggleRecord(recordId: string): Promise<void> {
-    if (state.expanded.has(recordId)) {
-      state.expanded.delete(recordId);
-    } else {
-      state.expanded.add(recordId);
-      if (state.run !== null) await loadTransitions(state.run.id, true);
-    }
-    render();
-  }
-
-  function renderRunSection(run: RunDetail): HTMLElement {
-    const section = view.el("section", { className: "run" });
-    section.appendChild(
-      view.renderRunHeader({
-        run,
-        errors: state.errors,
-        onAction: (action) => {
-          void runAction(action);
-        },
-      }),
-    );
-    section.appendChild(
-      view.renderRecordsTable({
-        records: state.records,
-        expanded: state.expanded,
-        transitionsOf: (recordId) => state.transitions.get(recordId) ?? [],
-        confirmed: state.confirmed,
-        operatorId: state.operatorId,
-        errors: state.errors,
-        onToggle: (recordId) => {
-          void toggleRecord(recordId);
-        },
-        onConfirm: (recordId, checked) => {
-          state.confirmed.set(recordId, checked);
-          render();
-        },
-        onAction: (recordId, action) => {
-          void recordAction(recordId, action);
-        },
-      }),
-    );
-    section.appendChild(
-      view.renderApprovals({
-        approvals: state.approvals,
-        operatorId: state.operatorId,
-        errors: state.errors,
-        onDecision: (requestId, decision) => {
-          void decide(requestId, decision);
-        },
-      }),
-    );
-    return section;
-  }
-
-  function render(): void {
-    view.clearNode(root);
-    const page = view.el("div", { className: "page" });
-    if (state.operatorProblem !== null) {
-      page.appendChild(
-        view.el("p", {
-          className: "operator-problem",
-          text: `${logic.OPERATOR_UNAVAILABLE_MESSAGE} The API said: ${state.operatorProblem}`,
-          attrs: { role: "status" },
-        }),
-      );
-    }
-    if (state.pageError !== null) {
-      page.appendChild(
-        view.el("p", { className: "page-error", text: state.pageError, attrs: { role: "alert" } }),
-      );
-    }
-    if (state.route.name === "runs") {
-      page.appendChild(view.renderRunsList(state.runs));
-    } else if (state.run === null) {
-      page.appendChild(view.el("p", { className: "muted", text: "Loading the run…" }));
-    } else {
-      page.appendChild(renderRunSection(state.run));
-    }
-    root.appendChild(page);
-  }
-
-  async function showRuns(): Promise<void> {
-    state.route = { name: "runs" };
-    state.expanded.clear();
-    state.transitions.clear();
-    await refresh();
-  }
-
-  async function openRun(runId: string): Promise<void> {
-    state.route = { name: "run", id: runId };
-    state.expanded.clear();
-    state.transitions.clear();
-    state.confirmed.clear();
-    state.errors.clear();
-    await refresh();
-  }
-
-  const maybeWindow: Window | undefined = typeof window === "undefined" ? undefined : window;
-  const onHashChange = (): void => {
-    const route = logic.routeFromHash(maybeWindow?.location.hash ?? "");
-    if (route.name === "run") {
-      void openRun(route.id);
-    } else {
-      void showRuns();
-    }
-  };
-  if (options.listenToHashChange === true && maybeWindow !== undefined) {
-    maybeWindow.addEventListener("hashchange", onHashChange);
-  }
-
-  render();
-
-  return {
-    refresh,
-    showRuns,
-    openRun,
-    render,
-    status: () => ({
-      route: state.route,
-      runId: state.run === null ? null : state.run.id,
-      runStatus: state.run === null ? null : state.run.status,
-      polling: poller.isRunning(),
-      operatorId: state.operatorId,
-      operatorProblem: state.operatorProblem,
-    }),
-    destroy: () => {
-      destroyed = true;
-      poller.stop();
-      if (options.listenToHashChange === true && maybeWindow !== undefined) {
-        maybeWindow.removeEventListener("hashchange", onHashChange);
-      }
-      view.clearNode(root);
-    },
-  };
-}
diff --git a/apps/web/src/lib/api.ts b/apps/web/src/lib/api.ts
new file mode 100644
index 0000000..afd63ae
--- /dev/null
+++ b/apps/web/src/lib/api.ts
@@ -0,0 +1,87 @@
+/**
+ * The API client. Every path is relative, so the page talks to the API it was served by and never
+ * to a host it made up.
+ *
+ * A refusal carries the API's own `detail` text, so a page can show it next to the button that
+ * caused it instead of inventing a sentence of its own.
+ */
+
+export class ApiError extends Error {
+  readonly status: number;
+  readonly detail: string;
+
+  constructor(status: number, detail: string) {
+    super(detail);
+    this.name = "ApiError";
+    this.status = status;
+    this.detail = detail;
+  }
+}
+
+const REFUSED = "The API refused the request";
+
+function parseJson(text: string): unknown {
+  if (text.trim() === "") return null;
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    return null;
+  }
+}
+
+function detailFromPayload(status: number, payload: unknown): string {
+  if (payload !== null && typeof payload === "object" && "detail" in payload) {
+    const detail = (payload as { detail: unknown }).detail;
+    if (typeof detail === "string" && detail.trim() !== "") return detail;
+  }
+  return `${REFUSED} (HTTP ${status}).`;
+}
+
+async function request<T>(
+  method: "GET" | "POST",
+  path: string,
+  body?: unknown,
+  signal?: AbortSignal,
+): Promise<T> {
+  const headers: Record<string, string> = { Accept: "application/json" };
+  const init: RequestInit = { method, headers };
+  if (signal !== undefined) init.signal = signal;
+  if (body !== undefined) {
+    headers["Content-Type"] = "application/json";
+    init.body = JSON.stringify(body);
+  }
+  let response: Response;
+  try {
+    response = await fetch(path, init);
+  } catch (error) {
+    if (signal !== undefined && signal.aborted) throw error;
+    throw new ApiError(0, "Could not reach the API.");
+  }
+  let text = "";
+  try {
+    text = await response.text();
+  } catch {
+    text = "";
+  }
+  if (!response.ok) {
+    throw new ApiError(response.status, detailFromPayload(response.status, parseJson(text)));
+  }
+  return parseJson(text) as T;
+}
+
+/** `GET` one JSON path, or throw an `ApiError` carrying the API's own explanation. */
+export function apiGet<T>(path: string, signal?: AbortSignal): Promise<T> {
+  return request<T>("GET", path, undefined, signal);
+}
+
+/** `POST` a JSON body (omit it when the API sends nothing) and read the JSON answer. */
+export function apiPost<T>(path: string, body?: unknown, signal?: AbortSignal): Promise<T> {
+  return request<T>("POST", path, body, signal);
+}
+
+/** The API's `detail` text, so a refusal can be shown next to the button that caused it. */
+export function errorText(error: unknown): string {
+  if (error instanceof ApiError) return error.detail;
+  if (error instanceof Error && error.message.trim() !== "") return error.message;
+  return "Something went wrong.";
+}
diff --git a/apps/web/src/lib/useJson.ts b/apps/web/src/lib/useJson.ts
new file mode 100644
index 0000000..09886d1
--- /dev/null
+++ b/apps/web/src/lib/useJson.ts
@@ -0,0 +1,64 @@
+/**
+ * One hook for every read: fetch a path once, and poll it while a number of milliseconds is given.
+ *
+ * The interval stops the moment the component goes away or `pollMs` becomes `null`, so a page that
+ * is finished polling makes no further requests.
+ */
+
+import { useCallback, useEffect, useState } from "react";
+
+import { apiGet, errorText } from "./api";
+
+/** How often a live page asks the API again. */
+export const POLL_INTERVAL_MS = 2000;
+
+export interface JsonState<T> {
+  data: T | null;
+  error: string | null;
+  loading: boolean;
+  /** Fetch once more now, without waiting for the next poll. */
+  reload: () => void;
+}
+
+export function useJson<T>(path: string | null, pollMs: number | null = null): JsonState<T> {
+  const [data, setData] = useState<T | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [loading, setLoading] = useState<boolean>(path !== null);
+  const [nonce, setNonce] = useState(0);
+
+  useEffect(() => {
+    if (path === null) {
+      setLoading(false);
+      return;
+    }
+    setLoading(true);
+    const controller = new AbortController();
+    let cancelled = false;
+    const load = async (): Promise<void> => {
+      try {
+        const payload = await apiGet<T>(path, controller.signal);
+        if (!cancelled) {
+          setData(payload);
+          setError(null);
+        }
+      } catch (failure) {
+        if (!cancelled && !controller.signal.aborted) setError(errorText(failure));
+      } finally {
+        if (!cancelled) setLoading(false);
+      }
+    };
+    void load();
+    // A number means "keep asking"; `null` means "this page is done".
+    const interval =
+      pollMs === null ? undefined : setInterval(() => void load(), Math.max(pollMs, 1));
+    return () => {
+      cancelled = true;
+      controller.abort();
+      if (interval !== undefined) clearInterval(interval);
+    };
+  }, [path, pollMs, nonce]);
+
+  const reload = useCallback(() => setNonce((value) => value + 1), []);
+
+  return { data, error, loading, reload };
+}
diff --git a/apps/web/src/lib/words.ts b/apps/web/src/lib/words.ts
new file mode 100644
index 0000000..dbff147
--- /dev/null
+++ b/apps/web/src/lib/words.ts
@@ -0,0 +1,163 @@
+/**
+ * The whole plain-words vocabulary. Every screen goes through this module, so the engine's words
+ * never reach a person's eyes (DESIGN.md §2, requirement 7).
+ *
+ * The mapping is the ticket's table; a state the table does not know falls back to "Waiting", and a
+ * reason it does not know is shown as it stands, because the runner writes those for people.
+ */
+
+export type Tone = "ok" | "help" | "live" | "idle";
+
+export interface Outcome {
+  label: string;
+  tone: Tone;
+}
+
+const WAITING: Outcome = { label: "Waiting", tone: "idle" };
+const CHECKING: Outcome = { label: "Checking…", tone: "live" };
+const DONE: Outcome = { label: "Done", tone: "ok" };
+const ALREADY_THERE: Outcome = { label: "Already there", tone: "idle" };
+const NEEDS_HELP: Outcome = { label: "Needs your help", tone: "help" };
+const DIDNT_WORK: Outcome = { label: "Didn't work", tone: "help" };
+
+/* engine state  ->  on screen */
+const ROW_STATES: Record<string, Outcome> = {
+  pending: WAITING,
+  claimed: WAITING,
+  prechecked: WAITING,
+  filling: WAITING,
+  submitting: CHECKING,
+  submitted_unverified: CHECKING,
+  reconciling: CHECKING,
+  verified: DONE,
+  skipped: ALREADY_THERE,
+  parked: NEEDS_HELP,
+  failed: DIDNT_WORK,
+};
+
+const RUN_STATUSES: Record<string, Outcome> = {
+  queued: { label: "Queued", tone: "idle" },
+  running: { label: "Running", tone: "live" },
+  paused: { label: "Paused", tone: "help" },
+  completed: { label: "Finished", tone: "ok" },
+  cancelled: { label: "Stopped", tone: "idle" },
+  failed: DIDNT_WORK,
+};
+
+/** A row's outcome in plain words. Unknown states fall back to "Waiting". */
+export function rowOutcome(state: string): Outcome {
+  return ROW_STATES[state] ?? WAITING;
+}
+
+/** A run's status in plain words. */
+export function runStatusWords(status: string): Outcome {
+  return RUN_STATUSES[status] ?? WAITING;
+}
+
+/* the reasons the runner writes  ->  one plain sentence */
+const REASONS: Record<string, string> = {
+  "attempts exhausted": "It didn't work after three tries.",
+  "already committed in an earlier run": "It was already added in an earlier run.",
+  "run cancelled": "The run was stopped before this row was reached.",
+  "dismissed by a person": "You dismissed this row.",
+  duplicate: "It was already there.",
+  "the option doesn't exist": "That answer isn't in the list on the site.",
+  "a value is missing": "A value it needs is missing from the row.",
+};
+
+/** "some_reason_code" -> "Some reason code", so a code nobody taught us is still readable. */
+function sentence(token: string): string {
+  const words = token.replace(/[_-]+/g, " ").replace(/\s+/g, " ").trim();
+  if (words === "") return "";
+  return words.charAt(0).toUpperCase() + words.slice(1);
+}
+
+/** The reason a row needs a person, in one plain sentence. */
+export function plainReason(reason: string | null, state?: string): string {
+  const key = (reason ?? "").trim();
+  if (key === "") {
+    return state === "skipped" ? "It was already there." : "Something went wrong.";
+  }
+  const known = REASONS[key.toLowerCase()];
+  if (known !== undefined) return known;
+  // The runner already writes its reasons for people, but a code we have never seen must still not
+  // reach the screen as an identifier.
+  const readable = sentence(key);
+  return /\.$/.test(readable) ? readable : `${readable}.`;
+}
+
+/*
+ * Every pause reason the PL-015 operator page already put into words, carried forward unchanged so
+ * this rebuild is not a regression: `paused_by_operator` is what the runs API sets, `operator_paused`
+ * is the older spelling, and both are accepted.
+ */
+const PAUSE_REASONS: Record<string, string> = {
+  login_required: "Log in to the site in the bound tab, then resume.",
+  challenge: "Solve the security challenge the site is showing in the bound tab, then resume.",
+  approval_required: "An approval request is waiting for your decision, then resume.",
+  awaiting_approval: "An approval request is waiting for your decision, then resume.",
+  paused_by_operator: "You paused this run. Resume when you are ready.",
+  operator_paused: "You paused this run. Resume when you are ready.",
+  manual_review: "A row in the table below needs your decision, then resume.",
+  rate_limited: "The site is rate limiting us. Wait a moment, then resume.",
+  destination_unreachable: "The site could not be reached. Check it, then resume.",
+};
+
+/** A pause reason in one actionable sentence, or `null` when there is none. */
+export function pauseReasonWords(reason: string | null): string | null {
+  const key = (reason ?? "").trim().toLowerCase();
+  if (key === "") return null;
+  const known = PAUSE_REASONS[key];
+  if (known !== undefined) return known;
+  return `Paused: ${sentence(key)}. Sort that out, then resume.`;
+}
+
+/** The states a run is still working through: `queued`, `running` or `paused`. */
+export function isOpenStatus(status: string | null): boolean {
+  return status === "queued" || status === "running" || status === "paused";
+}
+
+/** Which buttons a run's status offers. A finished run offers none of the three. */
+export function runActions(status: string): { pause: boolean; resume: boolean; cancel: boolean } {
+  const open = isOpenStatus(status);
+  return { pause: open, resume: status === "paused", cancel: open };
+}
+
+function plural(count: number, word: string): string {
+  return `${count} ${word}${count === 1 ? "" : "s"}`;
+}
+
+/** When something happened, as a person would say it. */
+export function relativeTime(iso: string | null, now: Date = new Date()): string {
+  if (iso === null || iso.trim() === "") return "Never";
+  const at = new Date(iso);
+  if (Number.isNaN(at.getTime())) return "Never";
+  const seconds = Math.floor((now.getTime() - at.getTime()) / 1000);
+  if (seconds < 60) return "Now";
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${plural(minutes, "minute")} ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${plural(hours, "hour")} ago`;
+  const days = Math.floor(hours / 24);
+  if (days === 1) return "Yesterday";
+  return `${plural(days, "day")} ago`;
+}
+
+/** "6 h 12 m" — minutes as hours and minutes, never negative. */
+export function durationWords(minutes: number): string {
+  const total = Math.max(0, Math.round(minutes));
+  const hours = Math.floor(total / 60);
+  const rest = total % 60;
+  if (hours === 0) return `${rest} m`;
+  if (rest === 0) return `${hours} h`;
+  return `${hours} h ${rest} m`;
+}
+
+/** "About 52 minutes saved" (or "About 1 hour saved"). */
+export function minutesSavedWords(minutes: number): string {
+  const total = Math.max(0, Math.round(minutes));
+  if (total === 0) return "Nothing saved yet";
+  if (total < 60) return `About ${plural(total, "minute")} saved`;
+  const hours = Math.max(1, Math.round(total / 60));
+  return `About ${plural(hours, "hour")} saved`;
+}
diff --git a/apps/web/src/logic.ts b/apps/web/src/logic.ts
deleted file mode 100644
index 821032d..0000000
--- a/apps/web/src/logic.ts
+++ /dev/null
@@ -1,359 +0,0 @@
-/**
- * The pure decisions this page makes: which buttons exist, what a pause reason means, when the
- * destination check gates an action, which ids a request body carries, and how the poll runs.
- *
- * Everything here is a plain exported function with no DOM in sight, so the tests next to it are
- * honest unit tests instead of DOM scraping.
- */
-
-import type { ApprovalDecision, ApprovalDecisionBody, RecordActionBody } from "./types";
-
-export const POLL_INTERVAL_MS = 2000;
-
-/** The exact words the confirmation carries. The ticket fixes them. */
-export const DESTINATION_CHECK_LABEL = "I checked the site and this record is not there";
-
-/** Said once, near the top of the page, when `GET /api/v1/operator` refuses. */
-export const OPERATOR_UNAVAILABLE_MESSAGE =
-  "The API did not give this page an operator identity, so every action that has to record who did it is disabled. Set PROCESSLENS_OPERATOR_ID and restart the API.";
-
-export type RunStatus = "queued" | "running" | "paused" | "completed" | "cancelled" | "failed";
-
-export const RUN_STATUSES: readonly RunStatus[] = [
-  "queued",
-  "running",
-  "paused",
-  "completed",
-  "cancelled",
-  "failed",
-];
-
-/** "Open" is queued, running or paused. */
-export const OPEN_STATUSES: readonly string[] = ["queued", "running", "paused"];
-
-export function isOpenStatus(status: string): boolean {
-  return OPEN_STATUSES.includes(status);
-}
-
-export function isFinishedStatus(status: string): boolean {
-  return isOpenStatus(status) === false;
-}
-
-/** Poll while — and only while — the run is open. */
-export function shouldPoll(status: string | null | undefined): boolean {
-  if (status === null || status === undefined) return false;
-  return isOpenStatus(status);
-}
-
-export interface RunActionAvailability {
-  pause: boolean;
-  resume: boolean;
-  cancel: boolean;
-}
-
-/** Pause and Cancel for an open run; Resume only when the run is paused. */
-export function runActions(status: string): RunActionAvailability {
-  const open = isOpenStatus(status);
-  return { pause: open, resume: status === "paused", cancel: open };
-}
-
-export type RunAction = "pause" | "resume" | "cancel";
-
-export function runActionLabel(action: RunAction): string {
-  if (action === "pause") return "Pause";
-  if (action === "resume") return "Resume";
-  return "Cancel";
-}
-
-/** "/" + words, with no host: the page and the API share one origin. */
-function path(...segments: string[]): string {
-  return `/api/v1/${segments.join("/")}`;
-}
-
-export function runsPath(): string {
-  return path("runs");
-}
-
-export function runPath(runId: string): string {
-  return path("runs", encodeURIComponent(runId));
-}
-
-export function runActionPath(runId: string, action: RunAction): string {
-  return path("runs", encodeURIComponent(runId), action);
-}
-
-export function recordsPath(runId: string): string {
-  return path("runs", encodeURIComponent(runId), "records");
-}
-
-export function transitionsPath(runId: string, after = 0): string {
-  const cursor = Number.isFinite(after) ? Math.max(0, Math.trunc(after)) : 0;
-  return `${path("runs", encodeURIComponent(runId), "transitions")}?after=${cursor}`;
-}
-
-export function approvalsPath(runId: string): string {
-  return path("runs", encodeURIComponent(runId), "approvals");
-}
-
-export function resultsCsvPath(runId: string): string {
-  return path("runs", encodeURIComponent(runId), "results.csv");
-}
-
-export function operatorPath(): string {
-  return path("operator");
-}
-
-export function approvalDecisionPath(): string {
-  return path("approvals");
-}
-
-export type RecordAction = "requeue" | "dismiss";
-
-export function recordActionPath(recordId: string, action: RecordAction): string {
-  return path("records", encodeURIComponent(recordId), action);
-}
-
-export function runHash(runId: string): string {
-  return `#/runs/${encodeURIComponent(runId)}`;
-}
-
-export interface RunsRoute {
-  name: "runs";
-}
-
-export interface RunRoute {
-  name: "run";
-  id: string;
-}
-
-export type Route = RunsRoute | RunRoute;
-
-/** The hash router: one page, no server-side rewrite, so `StaticFiles` needs no fallback. */
-export function routeFromHash(hash: string): Route {
-  const withoutHash = hash.startsWith("#") ? hash.slice(1) : hash;
-  const withSlash = withoutHash.startsWith("/") ? withoutHash : `/${withoutHash}`;
-  const match = /^\/runs\/([^/?#]+)/.exec(withSlash);
-  const captured = match === null ? undefined : match[1];
-  if (captured !== undefined && captured !== "") {
-    return { name: "run", id: decodeURIComponent(captured) };
-  }
-  return { name: "runs" };
-}
-
-/** "login_required" and friends, capitalised and readable. */
-export function humanizeToken(token: string): string {
-  const words = token.replace(/[_-]+/g, " ").replace(/\s+/g, " ").trim();
-  if (words === "") return "";
-  return words.charAt(0).toUpperCase() + words.slice(1);
-}
-
-const RUN_STATUS_TEXT: Record<string, string> = {
-  queued: "Queued",
-  running: "Running",
-  paused: "Paused",
-  completed: "Completed",
-  cancelled: "Cancelled",
-  failed: "Failed",
-};
-
-export function humanizeStatus(status: string): string {
-  const known = RUN_STATUS_TEXT[status];
-  return known === undefined ? humanizeToken(status) : known;
-}
-
-const PAUSE_REASON_TEXT: Record<string, string> = {
-  login_required: "Log in to the site in the bound tab, then resume.",
-  challenge: "Solve the security challenge the site is showing in the bound tab, then resume.",
-  approval_required: "An approval request is waiting for your decision, then resume.",
-  awaiting_approval: "An approval request is waiting for your decision, then resume.",
-  operator_paused: "You paused this run. Resume when you are ready.",
-  manual_review: "A record in the table below needs your decision, then resume.",
-  rate_limited: "The site is rate limiting us. Wait a moment, then resume.",
-  destination_unreachable: "The site could not be reached. Check it, then resume.",
-};
-
-/** The pause reason in words a person understands, or null when there is no reason. */
-export function humanizePauseReason(reason: string | null | undefined): string | null {
-  if (reason === null || reason === undefined) return null;
-  const key = reason.trim().toLowerCase();
-  if (key === "") return null;
-  const known = PAUSE_REASON_TEXT[key];
-  if (known !== undefined) return known;
-  return `Paused: ${humanizeToken(key)}. Sort that out, then resume.`;
-}
-
-export const COUNT_ORDER: readonly string[] = [
-  "total",
-  "verified",
-  "skipped",
-  "parked",
-  "failed",
-  "in_progress",
-];
-
-export interface CountEntry {
-  key: string;
-  label: string;
-  value: number;
-}
-
-/** Every count the API sent, in a stable order. */
-export function countEntries(counts: Record<string, number | undefined>): CountEntry[] {
-  const keys = [...COUNT_ORDER, ...Object.keys(counts).filter((key) => COUNT_ORDER.includes(key) === false)];
-  const entries: CountEntry[] = [];
-  for (const key of keys) {
-    const value = counts[key];
-    if (value === undefined) continue;
-    entries.push({ key, label: humanizeToken(key), value });
-  }
-  return entries;
-}
-
-export interface RecordActions {
-  requeue: boolean;
-  dismiss: boolean;
-}
-
-/** Re-queue and Dismiss appear for parked and failed records only. */
-export function recordActions(state: string): RecordActions {
-  const actionable = state === "parked" || state === "failed";
-  return { requeue: actionable, dismiss: actionable };
-}
-
-export interface ActionGateInput {
-  state: string;
-  commitAttempted: boolean;
-  confirmed: boolean;
-  operatorId: string | null;
-}
-
-export interface ActionGate {
-  shown: boolean;
-  /** A commit-attempted record needs the destination check ticked first. */
-  needsConfirmation: boolean;
-  /** Only the checked-destination path has to send the operator id. */
-  needsOperator: boolean;
-  disabled: boolean;
-}
-
-/**
- * The one place the page can get past the ledger's duplicate protection, so it is never one click.
- * A commit-attempted record keeps both buttons disabled until the confirmation is ticked, and
- * clearing the tick disables them again.
- */
-export function actionGate(input: ActionGateInput): ActionGate {
-  const actions = recordActions(input.state);
-  if (actions.requeue === false) {
-    return { shown: false, needsConfirmation: false, needsOperator: false, disabled: true };
-  }
-  const needsConfirmation = input.commitAttempted === true;
-  const needsOperator = needsConfirmation;
-  const confirmationMissing = needsConfirmation && input.confirmed !== true;
-  const operatorMissing = needsOperator && (input.operatorId === null || input.operatorId === "");
-  return {
-    shown: true,
-    needsConfirmation,
-    needsOperator,
-    disabled: confirmationMissing || operatorMissing,
-  };
-}
-
-export interface ActionBodyInput {
-  commitAttempted: boolean;
-  confirmed: boolean;
-  operatorId: string | null;
-  reason?: string | null;
-}
-
-/**
- * The exact body the record endpoints get. `destination_checked_by` is sent only after the check
- * has been confirmed, and the id is never invented.
- */
-export function actionBody(input: ActionBodyInput): RecordActionBody {
-  const body: RecordActionBody = {};
-  const reason = input.reason === undefined || input.reason === null ? "" : input.reason.trim();
-  if (reason !== "") body.reason = reason;
-  if (input.commitAttempted === true) {
-    if (input.confirmed !== true) {
-      throw new Error("A commit-attempted record needs the destination check confirmed first.");
-    }
-    if (input.operatorId === null || input.operatorId === "") {
-      throw new Error("A commit-attempted record needs the API's operator identity.");
-    }
-    body.destination_checked_by = input.operatorId;
-  }
-  return body;
-}
-
-export interface ApprovalBodyInput {
-  requestId: string;
-  decision: ApprovalDecision;
-  operatorId: string | null;
-  reason?: string | null;
-}
-
-export function approvalBody(input: ApprovalBodyInput): ApprovalDecisionBody {
-  if (input.operatorId === null || input.operatorId === "") {
-    throw new Error("Answering an approval needs the API's operator identity.");
-  }
-  const body: ApprovalDecisionBody = {
-    request_id: input.requestId,
-    decision: input.decision,
-    decided_by: input.operatorId,
-  };
-  const reason = input.reason === undefined || input.reason === null ? "" : input.reason.trim();
-  if (reason !== "") body.reason = reason;
-  return body;
-}
-
-export interface Timers {
-  setInterval: (handler: () => void, timeout: number) => unknown;
-  clearInterval: (handle: unknown) => void;
-}
-
-/** The real clock, swappable so a test can drive it. */
-export const DEFAULT_TIMERS: Timers = {
-  setInterval: (handler, timeout) => setInterval(handler, timeout) as unknown,
-  clearInterval: (handle) => {
-    clearInterval(handle as ReturnType<typeof setInterval>);
-  },
-};
-
-export interface Poller {
-  start: () => void;
-  stop: () => void;
-  isRunning: () => boolean;
-}
-
-export interface PollerOptions {
-  onTick: () => void;
-  shouldContinue: () => boolean;
-  intervalMs?: number;
-  timers?: Timers;
-}
-
-/**
- * A poll that stops itself as soon as it is no longer wanted. The interval is injectable and the
- * timer functions are looked up at call time, so fake timers work with it.
- */
-export function createPoller(options: PollerOptions): Poller {
-  const intervalMs = options.intervalMs ?? POLL_INTERVAL_MS;
-  const timers = options.timers ?? DEFAULT_TIMERS;
-  let handle: unknown = null;
-  const stop = (): void => {
-    if (handle === null) return;
-    timers.clearInterval(handle);
-    handle = null;
-  };
-  return {
-    start: (): void => {
-      if (handle !== null) return;
-      handle = timers.setInterval(() => {
-        options.onTick();
-        if (options.shouldContinue() === false) stop();
-      }, intervalMs);
-    },
-    stop,
-    isRunning: (): boolean => handle !== null,
-  };
-}
diff --git a/apps/web/src/main.ts b/apps/web/src/main.ts
deleted file mode 100644
index 3cd15d9..0000000
--- a/apps/web/src/main.ts
+++ /dev/null
@@ -1,10 +0,0 @@
-import "./styles.css";
-import { mountApp } from "./app";
-
-const root = document.getElementById("app");
-if (root === null) {
-  throw new Error("The page has no #app element to render into.");
-}
-
-const app = mountApp(root, { listenToHashChange: true });
-void app.refresh();
diff --git a/apps/web/src/main.tsx b/apps/web/src/main.tsx
new file mode 100644
index 0000000..292d11a
--- /dev/null
+++ b/apps/web/src/main.tsx
@@ -0,0 +1,31 @@
+/**
+ * The page's entry point: the self-hosted Public Sans faces, the shared styles, and the app.
+ *
+ * The four weights are the only ones the design uses, so exactly four faces are loaded. Nothing
+ * here reads `prefers-color-scheme`: the app is light only (DESIGN.md §4).
+ */
+
+import "@fontsource/public-sans/300.css";
+import "@fontsource/public-sans/400.css";
+import "@fontsource/public-sans/500.css";
+import "@fontsource/public-sans/600.css";
+import "./styles/tokens.css";
+import "./styles/global.css";
+import "./shell/shell.css";
+
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { BrowserRouter } from "react-router-dom";
+
+import { App } from "./App";
+
+const container = document.getElementById("root");
+if (container !== null) {
+  createRoot(container).render(
+    <StrictMode>
+      <BrowserRouter>
+        <App />
+      </BrowserRouter>
+    </StrictMode>,
+  );
+}
diff --git a/apps/web/src/pages/ComingSoon.tsx b/apps/web/src/pages/ComingSoon.tsx
new file mode 100644
index 0000000..d1ec365
--- /dev/null
+++ b/apps/web/src/pages/ComingSoon.tsx
@@ -0,0 +1,24 @@
+import { useLocation } from "react-router-dom";
+
+import { EmptyState } from "../shell/EmptyState";
+
+/**
+ * Every screen this ticket does not build yet: one sentence about what will appear here, and
+ * "Coming soon". The sentence is chosen from the path, so the router only has to render this.
+ */
+const SENTENCES: Record<string, string> = {
+  "/teach": "Teaching a new task from a recording is coming next.",
+  "/spreadsheets": "Your spreadsheets and the problems found in them will appear here.",
+  "/documents": "Your PDFs, and what was read from them, will appear here.",
+  "/saved-answers": "The answers you save for later runs will appear here.",
+  "/apps": "The sites each task may use will appear here.",
+  "/settings": "Your workspace, your people and how long screenshots are kept will appear here.",
+  "/help": "Short guides for each screen will appear here.",
+};
+
+const FALLBACK = "This screen will be built in a later release.";
+
+export function ComingSoon(): JSX.Element {
+  const { pathname } = useLocation();
+  return <EmptyState sentence={SENTENCES[pathname] ?? FALLBACK} />;
+}
diff --git a/apps/web/src/pages/Home.tsx b/apps/web/src/pages/Home.tsx
new file mode 100644
index 0000000..80f156e
--- /dev/null
+++ b/apps/web/src/pages/Home.tsx
@@ -0,0 +1,6 @@
+import { EmptyState } from "../shell/EmptyState";
+
+/** Placeholder: builder B replaces this file with the Home page of the approved mock. */
+export function Home(): JSX.Element {
+  return <EmptyState sentence="Your week at a glance will appear here." />;
+}
diff --git a/apps/web/src/pages/NeedsHelp.tsx b/apps/web/src/pages/NeedsHelp.tsx
new file mode 100644
index 0000000..a2f2a03
--- /dev/null
+++ b/apps/web/src/pages/NeedsHelp.tsx
@@ -0,0 +1,6 @@
+import { EmptyState } from "../shell/EmptyState";
+
+/** Placeholder: builder D replaces this file with the rows that need a person. */
+export function NeedsHelp(): JSX.Element {
+  return <EmptyState sentence="The rows that need your help will appear here." />;
+}
diff --git a/apps/web/src/pages/RunDetail.tsx b/apps/web/src/pages/RunDetail.tsx
new file mode 100644
index 0000000..6ffe97c
--- /dev/null
+++ b/apps/web/src/pages/RunDetail.tsx
@@ -0,0 +1,6 @@
+import { EmptyState } from "../shell/EmptyState";
+
+/** Placeholder: builder C replaces this file with the run page: progress and results. */
+export function RunDetail(): JSX.Element {
+  return <EmptyState sentence="This run's progress and results will appear here." />;
+}
diff --git a/apps/web/src/pages/Runs.tsx b/apps/web/src/pages/Runs.tsx
new file mode 100644
index 0000000..9cb467c
--- /dev/null
+++ b/apps/web/src/pages/Runs.tsx
@@ -0,0 +1,6 @@
+import { EmptyState } from "../shell/EmptyState";
+
+/** Placeholder: builder C replaces this file with the list of every run, live and past. */
+export function Runs(): JSX.Element {
+  return <EmptyState sentence="Every run, live and past, will appear here." />;
+}
diff --git a/apps/web/src/pages/TaskDetail.tsx b/apps/web/src/pages/TaskDetail.tsx
new file mode 100644
index 0000000..cca787b
--- /dev/null
+++ b/apps/web/src/pages/TaskDetail.tsx
@@ -0,0 +1,6 @@
+import { EmptyState } from "../shell/EmptyState";
+
+/** Placeholder: builder C replaces this file with the task page (steps in plain words, and runs). */
+export function TaskDetail(): JSX.Element {
+  return <EmptyState sentence="This task's steps and its runs will appear here." />;
+}
diff --git a/apps/web/src/pages/Tasks.tsx b/apps/web/src/pages/Tasks.tsx
new file mode 100644
index 0000000..0738232
--- /dev/null
+++ b/apps/web/src/pages/Tasks.tsx
@@ -0,0 +1,6 @@
+import { EmptyState } from "../shell/EmptyState";
+
+/** Placeholder: builder C replaces this file with the Tasks list of the approved mock. */
+export function Tasks(): JSX.Element {
+  return <EmptyState sentence="Your saved tasks will appear here." />;
+}
diff --git a/apps/web/src/shell/EmptyState.tsx b/apps/web/src/shell/EmptyState.tsx
new file mode 100644
index 0000000..4c7da7d
--- /dev/null
+++ b/apps/web/src/shell/EmptyState.tsx
@@ -0,0 +1,18 @@
+import type { CSSProperties, ReactNode } from "react";
+
+/**
+ * One sentence about what will appear here, plus "Coming soon".
+ *
+ * Every screen the ticket does not build yet uses this, so no page is ever blank.
+ */
+export function EmptyState(props: { sentence: string; action?: ReactNode }): JSX.Element {
+  return (
+    <section className="panel in" style={{ "--i": 1 } as CSSProperties}>
+      <div className="empty">
+        <p className="empty-sentence">{props.sentence}</p>
+        <p className="empty-soon">Coming soon</p>
+        {props.action === undefined ? null : <div className="empty-action">{props.action}</div>}
+      </div>
+    </section>
+  );
+}
diff --git a/apps/web/src/shell/Header.tsx b/apps/web/src/shell/Header.tsx
new file mode 100644
index 0000000..31f3d45
--- /dev/null
+++ b/apps/web/src/shell/Header.tsx
@@ -0,0 +1,26 @@
+import type { CSSProperties, ReactNode } from "react";
+
+import { Search } from "./Search";
+
+/**
+ * The header: the page's title, Search with its `Ctrl K` hint, the page's one primary action, and
+ * the avatar.
+ *
+ * The avatar is a plain circle with a person's outline -- nothing in this repository knows the
+ * operator's name, so no initials are invented.
+ */
+export function Header(props: { title: string; action?: ReactNode }): JSX.Element {
+  return (
+    <div className="head in" style={{ "--i": 0 } as CSSProperties}>
+      <h2>{props.title}</h2>
+      <Search />
+      {props.action === undefined || props.action === null ? null : props.action}
+      <span className="avatar" title="You" aria-label="You">
+        <svg className="i" viewBox="0 0 16 16" aria-hidden="true" focusable="false">
+          <circle cx="8" cy="5.6" r="2.6" />
+          <path d="M3.4 13.4c.7-2.4 2.6-3.6 4.6-3.6s3.9 1.2 4.6 3.6" />
+        </svg>
+      </span>
+    </div>
+  );
+}
diff --git a/apps/web/src/shell/Icons.tsx b/apps/web/src/shell/Icons.tsx
new file mode 100644
index 0000000..6742aea
--- /dev/null
+++ b/apps/web/src/shell/Icons.tsx
@@ -0,0 +1,86 @@
+/**
+ * The icon sprite from the approved mock, and the one way to use an icon: `<Icon name="home" />`.
+ *
+ * The symbols live in one hidden `<svg>` rendered by the shell, exactly as the mock does it, so the
+ * stroke weight and the 16 px box are the design's own.
+ */
+
+export type IconName =
+  | "home"
+  | "tasks"
+  | "hist"
+  | "help"
+  | "sheet"
+  | "doc"
+  | "map"
+  | "apps"
+  | "q"
+  | "gear"
+  | "search"
+  | "plus";
+
+/** One icon from the sprite. Decorative: the label beside it carries the meaning. */
+export function Icon({ name }: { name: IconName }): JSX.Element {
+  return (
+    <svg className="i" aria-hidden="true" focusable="false">
+      <use href={`#i-${name}`} />
+    </svg>
+  );
+}
+
+/** The hidden sprite itself, rendered once by the shell. */
+export function IconSprite(): JSX.Element {
+  return (
+    <svg width="0" height="0" style={{ position: "absolute" }} aria-hidden="true">
+      <symbol id="i-home" viewBox="0 0 16 16">
+        <path d="M2.5 7 8 2.5 13.5 7v6.5h-11z" />
+        <path d="M6.5 13.5V9.5h3v4" />
+      </symbol>
+      <symbol id="i-tasks" viewBox="0 0 16 16">
+        <rect x="2.5" y="2.5" width="11" height="11" rx="2" />
+        <path d="M5.5 6h5M5.5 8.5h5M5.5 11h3" />
+      </symbol>
+      <symbol id="i-hist" viewBox="0 0 16 16">
+        <path d="M2.8 8a5.2 5.2 0 1 0 1.5-3.7" />
+        <path d="M2.5 2.8v2.4h2.4M8 5.2V8l2 1.4" />
+      </symbol>
+      <symbol id="i-help" viewBox="0 0 16 16">
+        <circle cx="8" cy="8" r="5.5" />
+        <path d="M8 5v3.4M8 10.8v.1" />
+      </symbol>
+      <symbol id="i-sheet" viewBox="0 0 16 16">
+        <rect x="2.5" y="2.5" width="11" height="11" rx="1.5" />
+        <path d="M2.5 6.2h11M2.5 9.8h11M6.4 2.5v11" />
+      </symbol>
+      <symbol id="i-doc" viewBox="0 0 16 16">
+        <path d="M4 2.5h5.5L12 5v8.5H4z" />
+        <path d="M9.5 2.5V5H12M6 8.5h4M6 11h3" />
+      </symbol>
+      <symbol id="i-map" viewBox="0 0 16 16">
+        <path d="M3 5h6M3 11h10" />
+        <path d="m7 3 2 2-2 2M11 9l2 2-2 2" />
+      </symbol>
+      <symbol id="i-apps" viewBox="0 0 16 16">
+        <rect x="2.5" y="2.5" width="4.5" height="4.5" rx="1" />
+        <rect x="9" y="2.5" width="4.5" height="4.5" rx="1" />
+        <rect x="2.5" y="9" width="4.5" height="4.5" rx="1" />
+        <rect x="9" y="9" width="4.5" height="4.5" rx="1" />
+      </symbol>
+      <symbol id="i-q" viewBox="0 0 16 16">
+        <circle cx="8" cy="8" r="5.5" />
+        <path d="M6.4 6.4a1.7 1.7 0 0 1 3.2.6c0 1.1-1.6 1.4-1.6 2.4M8 11.2v.1" />
+      </symbol>
+      <symbol id="i-gear" viewBox="0 0 16 16">
+        <circle cx="8" cy="8" r="2" />
+        <path d="M8 2.2v1.6M8 12.2v1.6M2.2 8h1.6M12.2 8h1.6M3.9 3.9l1.1 1.1M11 11l1.1 1.1M3.9 12.1 5 11M11 5l1.1-1.1" />
+      </symbol>
+      <symbol id="i-search" viewBox="0 0 16 16">
+        <circle cx="7" cy="7" r="4.3" />
+        <path d="m10.3 10.3 3.2 3.2" />
+      </symbol>
+      <symbol id="i-plus" viewBox="0 0 16 16">
+        <path d="M8 3.2v9.6M3.2 8h9.6" />
+      </symbol>
+    </svg>
+  );
+}
diff --git a/apps/web/src/shell/Search.tsx b/apps/web/src/shell/Search.tsx
new file mode 100644
index 0000000..5754eb9
--- /dev/null
+++ b/apps/web/src/shell/Search.tsx
@@ -0,0 +1,77 @@
+import { useEffect, useState } from "react";
+import { Link } from "react-router-dom";
+
+import { useJson } from "../lib/useJson";
+import type { TaskRow } from "../types";
+import { Icon } from "./Icons";
+
+/**
+ * The header's search: a real, focusable panel over the task names.
+ *
+ * `Ctrl K` (or `Cmd K`) opens it, `Escape` closes it, and the typing filters the tasks the API
+ * knows about. It only asks for the list while it is open.
+ */
+export function Search(): JSX.Element {
+  const [open, setOpen] = useState(false);
+  const [query, setQuery] = useState("");
+  const { data } = useJson<TaskRow[]>(open ? "/api/v1/tasks" : null);
+
+  useEffect(() => {
+    const onKeyDown = (event: KeyboardEvent): void => {
+      if (event.key.toLowerCase() === "k" && (event.ctrlKey || event.metaKey)) {
+        event.preventDefault();
+        setOpen(true);
+        return;
+      }
+      if (event.key === "Escape") setOpen(false);
+    };
+    window.addEventListener("keydown", onKeyDown);
+    return () => window.removeEventListener("keydown", onKeyDown);
+  }, []);
+
+  const tasks = data ?? [];
+  const wanted = query.trim().toLowerCase();
+  const matches = tasks.filter((task) => task.name.toLowerCase().includes(wanted));
+
+  return (
+    <>
+      <button
+        type="button"
+        className="search"
+        aria-label="Search tasks"
+        aria-expanded={open}
+        onClick={() => setOpen(true)}
+      >
+        <Icon name="search" />
+        Search
+        <kbd>Ctrl K</kbd>
+      </button>
+      {open ? (
+        <div className="search-panel" role="dialog" aria-label="Search tasks">
+          <input
+            type="search"
+            aria-label="Task name"
+            placeholder="Type a task name"
+            value={query}
+            autoFocus
+            onChange={(event) => setQuery(event.target.value)}
+          />
+          {matches.length === 0 ? (
+            <p>No task has that name yet.</p>
+          ) : (
+            <ul className="rows">
+              {matches.slice(0, 8).map((task) => (
+                <li key={task.workflow_id}>
+                  <Link to={`/tasks/${task.workflow_id}`} onClick={() => setOpen(false)}>
+                    {task.name}
+                  </Link>
+                  <small>{task.app ?? ""}</small>
+                </li>
+              ))}
+            </ul>
+          )}
+        </div>
+      ) : null}
+    </>
+  );
+}
diff --git a/apps/web/src/shell/Shell.tsx b/apps/web/src/shell/Shell.tsx
new file mode 100644
index 0000000..679214f
--- /dev/null
+++ b/apps/web/src/shell/Shell.tsx
@@ -0,0 +1,64 @@
+import type { ReactNode } from "react";
+import { Link, Outlet, useLocation } from "react-router-dom";
+
+import { Header } from "./Header";
+import { Icon, IconSprite } from "./Icons";
+import { Sidebar } from "./Sidebar";
+
+interface PageChrome {
+  title: string;
+  /** The page's one primary action. At most one screen has one, and it is the near-black button. */
+  action?: () => ReactNode;
+  match: (path: string) => boolean;
+}
+
+/**
+ * The one primary action this ticket can offer: teaching the next task opens the Teach page, which
+ * arrives in a later ticket. Pages that own their own primary button leave this unset.
+ */
+function teachAction(): ReactNode {
+  return (
+    <Link className="btn primary" to="/teach">
+      <Icon name="plus" />
+      Teach a new task
+    </Link>
+  );
+}
+
+/* The order matters: a detail route is tested before its list route. */
+const PAGES: PageChrome[] = [
+  { match: (path) => path === "/", title: "Home", action: teachAction },
+  { match: (path) => path === "/needs-help", title: "Needs help" },
+  { match: (path) => path.startsWith("/tasks/"), title: "Task" },
+  { match: (path) => path === "/tasks", title: "Tasks", action: teachAction },
+  { match: (path) => path.startsWith("/runs/"), title: "Run" },
+  { match: (path) => path === "/runs", title: "Runs" },
+  { match: (path) => path === "/teach", title: "Teach a new task" },
+  { match: (path) => path === "/spreadsheets", title: "Spreadsheets" },
+  { match: (path) => path === "/documents", title: "Documents" },
+  { match: (path) => path === "/saved-answers", title: "Saved answers" },
+  { match: (path) => path === "/apps", title: "Apps" },
+  { match: (path) => path === "/settings", title: "Settings" },
+  { match: (path) => path === "/help", title: "Help" },
+];
+
+/**
+ * The app shell: the sidebar and the content column, with the header above whichever page the
+ * router chose.
+ */
+export function Shell(): JSX.Element {
+  const { pathname } = useLocation();
+  const page = PAGES.find((entry) => entry.match(pathname));
+  const action = page?.action;
+
+  return (
+    <div className="app">
+      <IconSprite />
+      <Sidebar />
+      <main>
+        <Header title={page?.title ?? "ProcessLens"} action={action === undefined ? null : action()} />
+        <Outlet />
+      </main>
+    </div>
+  );
+}
diff --git a/apps/web/src/shell/Sidebar.tsx b/apps/web/src/shell/Sidebar.tsx
new file mode 100644
index 0000000..c2ef363
--- /dev/null
+++ b/apps/web/src/shell/Sidebar.tsx
@@ -0,0 +1,110 @@
+import { NavLink } from "react-router-dom";
+
+import { useJson } from "../lib/useJson";
+import type { ExecutorSession, NeedsHelpRow } from "../types";
+import { Icon, type IconName } from "./Icons";
+
+interface Item {
+  to: string;
+  label: string;
+  icon: IconName;
+  /** Only Home lights up for exactly `/`, so a detail page does not light up two items at once. */
+  end?: boolean;
+}
+
+const TOP: Item[] = [
+  { to: "/", label: "Home", icon: "home", end: true },
+  { to: "/needs-help", label: "Needs help", icon: "help" },
+];
+
+const AUTOMATE: Item[] = [
+  { to: "/tasks", label: "Tasks", icon: "tasks" },
+  { to: "/runs", label: "Runs", icon: "hist" },
+];
+
+const YOUR_DATA: Item[] = [
+  { to: "/spreadsheets", label: "Spreadsheets", icon: "sheet" },
+  { to: "/documents", label: "Documents", icon: "doc" },
+  { to: "/saved-answers", label: "Saved answers", icon: "map" },
+];
+
+const CONNECT: Item[] = [{ to: "/apps", label: "Apps", icon: "apps" }];
+
+const FOOT: Item[] = [
+  { to: "/settings", label: "Settings", icon: "gear" },
+  { to: "/help", label: "Help", icon: "q" },
+];
+
+function itemLink(item: Item, extra?: React.ReactNode): JSX.Element {
+  return (
+    <NavLink
+      key={item.to}
+      to={item.to}
+      end={item.end === true}
+      className={({ isActive }) => (isActive ? "on" : undefined)}
+    >
+      <Icon name={item.icon} />
+      {item.label}
+      {extra}
+    </NavLink>
+  );
+}
+
+function Logo(): JSX.Element {
+  return (
+    <NavLink to="/" className="logo">
+      <svg viewBox="0 0 22 22" aria-hidden="true">
+        <circle cx="11" cy="11" r="9" fill="none" stroke="currentColor" strokeWidth="1.6" />
+        <path
+          d="M5.5 13.5c2-3.4 4-5 5.5-5s3.5 1.6 5.5 5"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="1.6"
+          strokeLinecap="round"
+        />
+      </svg>
+      ProcessLens
+    </NavLink>
+  );
+}
+
+/**
+ * The sidebar of DESIGN.md §6: the places, then the groups, then settings, help and the extension
+ * status at the bottom. The count beside "Needs help" is the same set the Needs help page shows,
+ * and it appears only when there is something to count.
+ */
+export function Sidebar(): JSX.Element {
+  const help = useJson<NeedsHelpRow[]>("/api/v1/needs-help");
+  const session = useJson<ExecutorSession>("/api/v1/executor/session");
+  const count = help.data?.length ?? 0;
+  const attached = session.data?.attached === true;
+
+  return (
+    <aside className="side">
+      <Logo />
+      <div className="navs">
+        <nav className="nav">
+          {TOP.map((item) =>
+            itemLink(
+              item,
+              item.to === "/needs-help" && count > 0 ? <span className="n">{count}</span> : null,
+            ),
+          )}
+        </nav>
+        <div className="grp">Automate</div>
+        <nav className="nav">{AUTOMATE.map((item) => itemLink(item))}</nav>
+        <div className="grp">Your data</div>
+        <nav className="nav">{YOUR_DATA.map((item) => itemLink(item))}</nav>
+        <div className="grp">Connect</div>
+        <nav className="nav">{CONNECT.map((item) => itemLink(item))}</nav>
+      </div>
+      <div className="side-foot">
+        <nav className="nav">{FOOT.map((item) => itemLink(item))}</nav>
+        <div className={attached ? "ext" : "ext off"}>
+          <i aria-hidden="true" />
+          {attached ? "Chrome connected" : "Chrome not connected"}
+        </div>
+      </div>
+    </aside>
+  );
+}
diff --git a/apps/web/src/shell/shell.css b/apps/web/src/shell/shell.css
new file mode 100644
index 0000000..b1bcfb8
--- /dev/null
+++ b/apps/web/src/shell/shell.css
@@ -0,0 +1,56 @@
+/* The app shell: the frosted sidebar, the content column and the header, ported from
+   internal/docs/design/home-mock.html. */
+
+.app { display: grid; grid-template-columns: 216px minmax(0, 1fr); min-height: 100vh; }
+
+/* sidebar: the four places, then settings and the extension status at the bottom */
+.side { position: sticky; top: 0; height: 100vh; padding: 16px 12px; display: flex; flex-direction: column; gap: 22px;
+  background: var(--glass); backdrop-filter: blur(18px); -webkit-backdrop-filter: blur(18px); border-right: 1px solid var(--glass-line); }
+.logo { display: flex; align-items: center; gap: 9px; font-weight: 600; font-size: 15px; padding: 2px 8px; color: var(--ink); text-decoration: none; }
+.logo svg { width: 21px; height: 21px; }
+.nav { display: grid; gap: 2px; }
+.nav a { display: flex; align-items: center; gap: 10px; padding: 8px 10px; border-radius: 8px; color: var(--ink-2); text-decoration: none; font-weight: 500; }
+.nav a:hover { background: var(--hair); color: var(--ink); }
+.nav a.on { background: var(--glass-strong); color: var(--ink); box-shadow: 0 1px 2px rgba(0,0,0,.04), inset 0 0 0 1px var(--hair); }
+.nav .n { margin-left: auto; font-size: 12px; font-weight: 600; color: var(--help); }
+.navs { display: grid; gap: 4px; overflow-y: auto; }
+.grp { font-size: 12px; color: var(--muted); padding: 12px 10px 4px; }
+.side-foot { margin-top: auto; display: grid; gap: 8px; }
+.ext { display: flex; gap: 9px; align-items: center; padding: 8px 10px; font-size: 13px; color: var(--ink-2); }
+.ext i { width: 8px; height: 8px; border-radius: 50%; background: var(--ok); flex: none; box-shadow: 0 0 0 3px color-mix(in srgb, var(--ok) 16%, transparent); }
+.ext.off i { background: var(--muted); box-shadow: 0 0 0 3px color-mix(in srgb, var(--muted) 16%, transparent); }
+
+/* the content column */
+main { min-width: 0; padding: 16px clamp(16px, 3vw, 40px) 64px; display: grid; gap: 30px; align-content: start; max-width: 1180px; }
+
+/* header */
+.head { display: flex; align-items: center; gap: 12px; min-height: 44px; flex-wrap: wrap; }
+.head h2 { margin: 0; font-size: 15px; font-weight: 600; }
+.search { margin-left: auto; display: flex; align-items: center; gap: 8px; width: min(300px, 40vw); padding: 8px 11px; border-radius: 9px; border: 1px solid var(--hair-2); background: var(--glass-strong); color: var(--muted); font-size: 13.5px; cursor: pointer; font-family: var(--font); }
+.search kbd { margin-left: auto; font: 500 11px var(--font); border: 1px solid var(--hair-2); border-radius: 4px; padding: 0 5px; color: var(--ink-2); }
+.avatar { width: 32px; height: 32px; border-radius: 50%; background: var(--glass-strong); border: 1px solid var(--hair-2); display: grid; place-items: center; color: var(--ink-2); flex: none; }
+
+/* the Ctrl K search panel */
+.search-panel { position: absolute; right: clamp(16px, 3vw, 40px); top: 62px; z-index: 20; width: min(380px, 90vw); padding: 12px 0 8px; border-radius: 14px;
+  background: var(--glass-strong); backdrop-filter: blur(18px); -webkit-backdrop-filter: blur(18px); border: 1px solid var(--hair-2); box-shadow: 0 18px 40px -24px rgba(0,0,0,.35); }
+.search-panel input { width: calc(100% - 32px); margin: 0 16px 8px; padding: 8px 10px; border-radius: 9px; border: 1px solid var(--hair-2); background: #fff; color: var(--ink); font: 400 14px var(--font); }
+.search-panel .rows li { padding: 10px 16px; }
+.search-panel .rows a { color: var(--ink); text-decoration: none; font-weight: 500; }
+.search-panel .rows a:hover { text-decoration: underline; }
+.search-panel p { margin: 4px 16px 0; color: var(--muted); font-size: 13px; }
+
+/* empty states */
+.empty { padding: 26px 20px 30px; display: grid; gap: 6px; justify-items: start; }
+.empty-sentence { margin: 0; color: var(--ink-2); font-size: 15px; }
+.empty-soon { margin: 0; color: var(--muted); font-size: 13px; }
+.empty-action { margin-top: 8px; }
+
+@media (max-width: 780px) {
+  .app { grid-template-columns: minmax(0,1fr); }
+  .side { position: static; height: auto; flex-direction: row; align-items: center; border-right: 0; border-bottom: 1px solid var(--glass-line); overflow-x: auto; gap: 12px; }
+  .side .nav { grid-auto-flow: column; }
+  .navs { grid-auto-flow: column; align-items: center; }
+  .grp { display: none; }
+  .side-foot, .search { display: none; }
+  .search-panel { left: 12px; right: 12px; top: 56px; width: auto; }
+}
diff --git a/apps/web/src/styles.css b/apps/web/src/styles.css
deleted file mode 100644
index ab35e5f..0000000
--- a/apps/web/src/styles.css
+++ /dev/null
@@ -1,126 +0,0 @@
-/* No external fonts and no @import: this page is served from loopback and must not reach out. */
-:root {
-  color-scheme: light dark;
-  font-family: system-ui, -apple-system, Segoe UI, Roboto, sans-serif;
-  font-size: 15px;
-  line-height: 1.45;
-}
-
-body {
-  margin: 0;
-  padding: 1rem 1.25rem 3rem;
-  background: Canvas;
-  color: CanvasText;
-}
-
-.topbar {
-  display: flex;
-  align-items: baseline;
-  gap: 1rem;
-  border-bottom: 1px solid color-mix(in srgb, CanvasText 20%, transparent);
-  padding-bottom: 0.5rem;
-}
-
-.topbar h1 {
-  font-size: 1.1rem;
-  margin: 0;
-}
-
-h2 {
-  font-size: 1rem;
-  margin: 1.5rem 0 0.5rem;
-}
-
-table {
-  border-collapse: collapse;
-  width: 100%;
-}
-
-th,
-td {
-  border: 1px solid color-mix(in srgb, CanvasText 25%, transparent);
-  padding: 0.35rem 0.5rem;
-  text-align: left;
-  vertical-align: top;
-}
-
-th {
-  font-weight: 600;
-}
-
-.muted {
-  opacity: 0.7;
-}
-
-.action,
-.record-toggle {
-  margin-right: 0.35rem;
-}
-
-.action-error {
-  display: inline-block;
-  margin-left: 0.4rem;
-  padding: 0.1rem 0.35rem;
-  border: 1px solid currentColor;
-  border-radius: 3px;
-  color: #a30000;
-  font-size: 0.9em;
-}
-
-.operator-problem,
-.page-error {
-  border: 1px solid currentColor;
-  border-radius: 4px;
-  padding: 0.5rem 0.6rem;
-}
-
-.operator-problem {
-  background: color-mix(in srgb, gold 25%, transparent);
-}
-
-.page-error {
-  background: color-mix(in srgb, red 15%, transparent);
-}
-
-.destination-check {
-  display: block;
-  margin-bottom: 0.4rem;
-}
-
-.destination-check-label {
-  margin-left: 0.35rem;
-}
-
-.counts {
-  display: flex;
-  flex-wrap: wrap;
-  gap: 0.75rem;
-  list-style: none;
-  padding: 0;
-  margin: 0.5rem 0;
-}
-
-.run-actions,
-.approval-actions {
-  display: flex;
-  flex-wrap: wrap;
-  align-items: center;
-  gap: 0.35rem;
-  margin: 0.5rem 0;
-}
-
-.approval {
-  border: 1px solid color-mix(in srgb, CanvasText 25%, transparent);
-  border-radius: 4px;
-  padding: 0.5rem 0.75rem;
-  margin-bottom: 0.75rem;
-}
-
-.record-key-value {
-  margin-left: 0.5rem;
-  word-break: break-word;
-}
-
-.transitions-table {
-  margin-top: 0.25rem;
-}
diff --git a/apps/web/src/styles/global.css b/apps/web/src/styles/global.css
new file mode 100644
index 0000000..d0b9a75
--- /dev/null
+++ b/apps/web/src/styles/global.css
@@ -0,0 +1,87 @@
+/* Shared primitives, ported from internal/docs/design/home-mock.html: the page background, the
+   focus ring, the buttons, the panels, the tables, the live dot and the blur-in entrance. */
+
+* { box-sizing: border-box; }
+html, body { min-height: 100%; }
+body {
+  margin: 0; color: var(--ink); font: 14.5px/1.5 var(--font); -webkit-font-smoothing: antialiased;
+  background:
+    radial-gradient(1200px 560px at 10% -10%, var(--fog-1) 0%, transparent 60%),
+    radial-gradient(1000px 640px at 105% 105%, var(--fog-3) 0%, transparent 62%),
+    linear-gradient(180deg, var(--fog-1), var(--fog-2));
+  background-attachment: fixed; background-color: var(--fog-2);
+}
+:focus-visible { outline: 2px solid var(--ink-2); outline-offset: 2px; border-radius: 6px; }
+svg.i { width: 16px; height: 16px; flex: none; fill: none; stroke: currentColor; stroke-width: 1.5; stroke-linecap: round; stroke-linejoin: round; }
+
+/* buttons */
+.btn { display: inline-flex; align-items: center; gap: 8px; font: 500 14px var(--font); border-radius: 9px; padding: 9px 14px; cursor: pointer; border: 1px solid transparent; text-decoration: none; white-space: nowrap; transition: transform .15s ease; background: none; color: var(--ink); }
+.btn.primary { background: linear-gradient(180deg, var(--primary-a), var(--primary-b)); color: var(--on-primary); box-shadow: inset 0 1px 0 rgba(255,255,255,.35), 0 1px 2px rgba(120,90,20,.2), 0 8px 18px -10px rgba(120,90,20,.45); }
+.btn.primary:hover { transform: translateY(-1px); }
+.btn.quiet { background: var(--glass-strong); color: var(--ink); border-color: var(--hair-2); padding: 7px 12px; font-size: 13.5px; }
+.btn.quiet:hover { border-color: var(--ink-2); }
+.btn:disabled { opacity: .5; cursor: not-allowed; transform: none; }
+
+/* headline and the time-saved figure */
+.hero { display: flex; justify-content: space-between; align-items: flex-end; gap: 24px; flex-wrap: wrap; }
+.big { margin: 6px 0 0; font-size: clamp(34px, 4.2vw, 52px); font-weight: 300; letter-spacing: -0.04em; line-height: 1.04; }
+.big span { color: var(--muted); }
+.lede { margin: 12px 0 0; color: var(--ink-2); font-size: 15.5px; }
+.saved-fig { text-align: right; display: grid; gap: 2px; padding: 14px 20px; border-radius: 14px; background: linear-gradient(180deg, rgba(255,255,255,.85), var(--gold-soft)); border: 1px solid var(--gold-line); }
+.saved-fig b { font-size: clamp(30px, 3.4vw, 42px); font-weight: 300; letter-spacing: -0.035em; color: var(--gold-deep); font-variant-numeric: tabular-nums; line-height: 1.05; }
+.saved-fig span { color: var(--ink-2); font-size: 13.5px; }
+.saved-fig small { color: var(--muted); font-size: 12.5px; }
+
+/* panels */
+.panel { background: var(--glass); backdrop-filter: blur(18px); -webkit-backdrop-filter: blur(18px); border: 1px solid var(--glass-line); border-radius: 14px;
+  box-shadow: 0 1px 1px rgba(0,0,0,.02), 0 18px 40px -30px rgba(0,0,0,.28); min-width: 0; }
+.panel-h { display: flex; align-items: center; justify-content: space-between; gap: 12px; padding: 15px 20px 6px; }
+.panel-h h3 { margin: 0; font-size: 15px; font-weight: 600; }
+.panel-h a { color: var(--ink-2); font-size: 13.5px; text-decoration: none; }
+.panel-h a:hover { color: var(--ink); }
+.two { display: grid; grid-template-columns: minmax(0, 1.3fr) minmax(0, 1fr); gap: 18px; }
+
+/* row lists */
+.rows { list-style: none; margin: 0; padding: 0 0 6px; }
+.rows li { display: grid; grid-template-columns: minmax(0,1fr) auto; gap: 14px; align-items: center; padding: 12px 20px; border-top: 1px solid var(--hair); }
+.rows li:first-child { border-top: 0; }
+.rows b { font-weight: 500; }
+.rows p { margin: 1px 0 0; color: var(--ink-2); font-size: 14px; }
+
+/* the live run */
+.run { padding: 10px 20px 20px; display: grid; gap: 12px; }
+.run b { font-weight: 500; font-size: 15px; }
+.track { height: 6px; border-radius: 6px; background: var(--hair-2); overflow: hidden; }
+.track i { display: block; height: 100%; width: 0; background: linear-gradient(90deg, var(--primary-a), var(--primary-b)); border-radius: 6px; transition: width .9s cubic-bezier(.3,.1,.2,1); }
+.run .meta { display: flex; justify-content: space-between; gap: 12px; color: var(--ink-2); font-size: 13.5px; font-variant-numeric: tabular-nums; }
+.live { display: inline-flex; align-items: center; gap: 7px; color: var(--live); font-size: 13px; font-weight: 500; }
+.live i { width: 6px; height: 6px; border-radius: 50%; background: var(--live); animation: pulse 1.8s ease-out infinite; }
+@keyframes pulse { 0% { box-shadow: 0 0 0 0 color-mix(in srgb, var(--live) 55%, transparent); } 70%, 100% { box-shadow: 0 0 0 6px transparent; } }
+
+/* tables */
+table { width: 100%; border-collapse: collapse; }
+th { text-align: left; font-weight: 500; font-size: 13px; color: var(--muted); padding: 10px 20px; border-bottom: 1px solid var(--hair); }
+td { padding: 14px 20px; border-bottom: 1px solid var(--hair); vertical-align: middle; }
+tbody tr:last-child td { border-bottom: 0; }
+tbody tr:hover { background: color-mix(in srgb, var(--glass-strong) 75%, transparent); }
+td b { font-weight: 500; display: block; }
+td small { color: var(--muted); font-size: 13px; }
+.res { display: inline-flex; align-items: center; gap: 8px; }
+.res::before { content: ""; width: 7px; height: 7px; border-radius: 50%; background: currentColor; }
+.res.ok { color: var(--ok); } .res.help { color: var(--help); } .res.live { color: var(--live); } .res.idle { color: var(--muted); }
+td.act { text-align: right; width: 1%; white-space: nowrap; }
+
+/* the blur-in entrance: first render of a page only, staggered by --i */
+.in { animation: blurin .85s cubic-bezier(.2,.7,.2,1) both; animation-delay: calc(var(--i, 0) * 70ms); }
+@keyframes blurin { from { opacity: 0; filter: blur(10px); transform: translateY(8px); } }
+@media (prefers-reduced-motion: reduce) {
+  .in, .live i { animation: none !important; }
+  .track i { transition: none; }
+  .in { opacity: 1; filter: none; transform: none; }
+}
+
+@media (max-width: 1040px) { .two { grid-template-columns: minmax(0,1fr); } }
+@media (max-width: 780px) {
+  th:nth-child(2), td:nth-child(2) { display: none; }
+  .saved-fig { text-align: left; }
+}
diff --git a/apps/web/src/styles/tokens.css b/apps/web/src/styles/tokens.css
new file mode 100644
index 0000000..bda255e
--- /dev/null
+++ b/apps/web/src/styles/tokens.css
@@ -0,0 +1,12 @@
+/* The design tokens, copied verbatim from internal/docs/design/home-mock.html.
+   Light only: an internal tool used all day in an office. Gold is the one accent. */
+:root {
+  color-scheme: light;
+  --fog-1: #fdfdfc; --fog-2: #f4f5f3; --fog-3: #e9ebe6;
+  --glass: rgba(255,255,255,.78); --glass-line: rgba(255,255,255,.95); --glass-strong: rgba(255,255,255,.95);
+  --ink: #2a2d2b; --ink-2: #5d6461; --muted: #959c98; --hair: rgba(42,45,43,.07); --hair-2: rgba(42,45,43,.13);
+  --gold: #c8a04a; --gold-deep: #9c7a2c; --gold-soft: #f7f0de; --gold-line: #e8d6aa;
+  --primary-a: #d9b663; --primary-b: #c59a3f; --on-primary: #2b2210;
+  --ok: #3d7a55; --help: #b0532c; --live: #b8892f;
+  --font: "Public Sans", "Helvetica Neue", Arial, sans-serif;
+}
diff --git a/apps/web/src/types.ts b/apps/web/src/types.ts
index 566329c..4a54d1b 100644
--- a/apps/web/src/types.ts
+++ b/apps/web/src/types.ts
@@ -1,13 +1,9 @@
-/** The shapes the API returns, exactly as the ticket freezes them. */
-
-export interface RunCounts {
-  total: number;
-  verified: number;
-  skipped: number;
-  parked: number;
-  failed: number;
-  in_progress: number;
-}
+/**
+ * The shapes the API returns, exactly as the ticket freezes them.
+ *
+ * Every screen reads these types, so a page never invents a field: if a value is not here, the API
+ * does not send it yet.
+ */
 
 /** One row of `GET /api/v1/runs`. */
 export interface RunSummary {
@@ -20,26 +16,18 @@ export interface RunSummary {
   counts: Record<string, number>;
 }
 
-/** An approval request. */
-export interface ApprovalRequest {
-  id: string;
-  run_record_id: string;
-  step_id: string;
-  kind: string;
-  shown: Record<string, unknown>;
-  created_at: string;
-}
-
-/** `GET /api/v1/runs/{id}`. */
+/** `GET /api/v1/runs/{id}`. `started_at`/`finished_at` are what a finished run's time saved needs. */
 export interface RunDetail {
   id: string;
   status: string;
   pause_reason: string | null;
-  counts: Partial<RunCounts>;
+  counts: Record<string, number>;
   open_approval: ApprovalRequest | null;
+  started_at?: string | null;
+  finished_at?: string | null;
 }
 
-/** One row of `GET /api/v1/runs/{id}/records`. */
+/** One row of `GET /api/v1/runs/{id}/records`: a row of the spreadsheet, and where it got to. */
 export interface RecordRow {
   id: string;
   record_key: string;
@@ -62,6 +50,26 @@ export interface Transition {
   at: string;
 }
 
+/** An approval request a run is waiting on. */
+export interface ApprovalRequest {
+  id: string;
+  run_record_id: string;
+  step_id: string;
+  kind: string;
+  shown: Record<string, unknown>;
+  created_at: string;
+}
+
+export type ApprovalDecision = "approved" | "rejected";
+
+/** The body of `POST /api/v1/approvals`. */
+export interface ApprovalDecisionBody {
+  request_id: string;
+  decision: ApprovalDecision;
+  decided_by: string;
+  reason?: string;
+}
+
 /** `GET /api/v1/operator`. */
 export interface OperatorInfo {
   operator_id: string;
@@ -79,12 +87,65 @@ export interface RecordActionResponse {
   state: string;
 }
 
-export type ApprovalDecision = "approved" | "rejected";
+/** One row of `GET /api/v1/needs-help`, and one entry of `home.needs_help`. */
+export interface NeedsHelpRow {
+  record_id: string;
+  run_id: string;
+  task_name: string;
+  row: string;
+  state: string;
+  reason: string | null;
+  commit_attempted: boolean;
+}
 
-/** The body of `POST /api/v1/approvals`. */
-export interface ApprovalDecisionBody {
-  request_id: string;
-  decision: ApprovalDecision;
-  decided_by: string;
-  reason?: string;
+/** One running run on `GET /api/v1/home`. */
+export interface RunningRun {
+  run_id: string;
+  task_name: string;
+  done: number;
+  total: number;
+  already_there: number;
+}
+
+/** One task on `GET /api/v1/tasks`, and one entry of `home.tasks`. */
+export interface TaskRow {
+  workflow_id: string;
+  recipe_version_id: string;
+  name: string;
+  app: string | null;
+  last_run: TaskLastRun | null;
+}
+
+/** A task's most recent run. */
+export interface TaskLastRun {
+  run_id: string;
+  status: string;
+  started_at: string | null;
+  counts: Record<string, number>;
+}
+
+/** `GET /api/v1/home`. */
+export interface HomeSummary {
+  window_days: number;
+  counts: { done: number; already_there: number; needs_help: number };
+  minutes_saved: number;
+  needs_help: NeedsHelpRow[];
+  running: RunningRun[];
+  tasks: TaskRow[];
+}
+
+/** `GET /api/v1/executor/session`: whether the Chrome extension is attached right now. */
+export interface ExecutorSession {
+  attached: boolean;
+}
+
+/**
+ * One step of a task, in plain words (builder C builds the sentences; the type is shared so every
+ * page shows a step the same way).
+ */
+export interface StepWords {
+  /** One sentence: "Open Odoo CRM", "Type the email", "Click Save". */
+  title: string;
+  /** An optional second line, such as the value a step fills in. */
+  detail?: string;
 }
diff --git a/apps/web/src/view.ts b/apps/web/src/view.ts
deleted file mode 100644
index 05792f6..0000000
--- a/apps/web/src/view.ts
+++ /dev/null
@@ -1,382 +0,0 @@
-/**
- * The DOM layer, and nothing else. Every value in it — including anything that came out of a user's
- * CSV — goes in through `textContent`. There is no `innerHTML` in this file, by design.
- */
-
-import * as logic from "./logic";
-import type { ApprovalDecision, ApprovalRequest, RecordRow, RunDetail, RunSummary, Transition } from "./types";
-
-export interface ElementOptions {
-  className?: string;
-  text?: string;
-  /** Static attribute names and values this module owns; never a value from the API. */
-  attrs?: Record<string, string>;
-}
-
-export function el<K extends keyof HTMLElementTagNameMap>(
-  tag: K,
-  options: ElementOptions = {},
-): HTMLElementTagNameMap[K] {
-  const node = document.createElement(tag);
-  if (options.className !== undefined) node.className = options.className;
-  if (options.text !== undefined) node.textContent = options.text;
-  if (options.attrs !== undefined) {
-    for (const [name, value] of Object.entries(options.attrs)) node.setAttribute(name, value);
-  }
-  return node;
-}
-
-export function clearNode(node: HTMLElement): void {
-  while (node.firstChild !== null) node.removeChild(node.firstChild);
-}
-
-export interface ButtonOptions {
-  className?: string;
-  disabled?: boolean;
-  onClick?: () => void;
-}
-
-export function button(label: string, options: ButtonOptions = {}): HTMLButtonElement {
-  const node = el("button", { className: options.className ?? "action", text: label });
-  node.type = "button";
-  node.disabled = options.disabled === true;
-  if (options.onClick !== undefined) node.addEventListener("click", options.onClick);
-  return node;
-}
-
-/** The API's `detail` text, rendered right where the button that failed is. */
-export function errorSpan(text: string | undefined): HTMLSpanElement | null {
-  if (text === undefined || text === "") return null;
-  return el("span", { className: "action-error", text, attrs: { role: "alert" } });
-}
-
-export function describeValue(value: unknown): string {
-  if (value === undefined) return "—";
-  if (value === null) return "null";
-  if (typeof value === "string") return value;
-  if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
-    return String(value);
-  }
-  try {
-    return JSON.stringify(value) ?? String(value);
-  } catch {
-    return String(value);
-  }
-}
-
-function textOr(value: string | null | undefined, fallback: string): string {
-  if (value === null || value === undefined) return fallback;
-  const trimmed = value.trim();
-  return trimmed === "" ? fallback : value;
-}
-
-function countsLine(counts: Record<string, number>): string {
-  const entries = logic.countEntries(counts);
-  if (entries.length === 0) return "—";
-  return entries.map((entry) => `${entry.label.toLowerCase()} ${entry.value}`).join(" · ");
-}
-
-function recipeLabel(run: RunSummary): string {
-  const name = run.recipe_name === null ? "" : run.recipe_name;
-  const version = run.recipe_version === null ? "" : run.recipe_version;
-  if (name === "" && version === "") return "—";
-  return version === "" ? name : `${name} v${version}`;
-}
-
-/** The runs list. Every row links to its run. */
-export function renderRunsList(runs: readonly RunSummary[]): HTMLElement {
-  const section = el("section", { className: "runs" });
-  section.appendChild(el("h2", { text: "Runs" }));
-  if (runs.length === 0) {
-    section.appendChild(el("p", { className: "muted", text: "No runs yet." }));
-    return section;
-  }
-  const table = el("table", { className: "runs-table" });
-  const head = el("tr");
-  for (const label of ["Run", "Status", "Pause reason", "Recipe", "Created", "Counts"]) {
-    head.appendChild(el("th", { text: label }));
-  }
-  const thead = el("thead");
-  thead.appendChild(head);
-  table.appendChild(thead);
-  const tbody = el("tbody");
-  for (const run of runs) {
-    const row = el("tr", { className: "run-row" });
-    const idCell = el("td", { className: "run-id" });
-    idCell.appendChild(el("a", { text: run.id, attrs: { href: logic.runHash(run.id) } }));
-    row.appendChild(idCell);
-    row.appendChild(el("td", { className: "run-status", text: logic.humanizeStatus(run.status) }));
-    row.appendChild(
-      el("td", { className: "run-pause-reason", text: logic.humanizePauseReason(run.pause_reason) ?? "—" }),
-    );
-    row.appendChild(el("td", { className: "run-recipe", text: recipeLabel(run) }));
-    row.appendChild(el("td", { className: "run-created", text: textOr(run.created_at, "—") }));
-    row.appendChild(el("td", { className: "run-counts", text: countsLine(run.counts) }));
-    tbody.appendChild(row);
-  }
-  table.appendChild(tbody);
-  section.appendChild(table);
-  return section;
-}
-
-export interface RunHeaderOptions {
-  run: RunDetail;
-  errors: ReadonlyMap<string, string>;
-  onAction: (action: logic.RunAction) => void;
-}
-
-/** Status, pause reason in plain words, counts, the buttons the status allows, and results.csv. */
-export function renderRunHeader(options: RunHeaderOptions): HTMLElement {
-  const run = options.run;
-  const section = el("section", { className: "run-header" });
-  section.appendChild(el("h2", { className: "run-title", text: `Run ${run.id}` }));
-
-  const statusLine = el("p", { className: "run-status-line" });
-  statusLine.appendChild(el("span", { className: `run-status run-status-${run.status}`, text: logic.humanizeStatus(run.status) }));
-  section.appendChild(statusLine);
-
-  const pauseText = logic.humanizePauseReason(run.pause_reason);
-  section.appendChild(
-    el("p", {
-      className: pauseText === null ? "pause-reason muted" : "pause-reason",
-      text: pauseText ?? "Not paused.",
-    }),
-  );
-
-  const counts = el("ul", { className: "counts" });
-  for (const entry of logic.countEntries(run.counts)) {
-    const item = el("li", { className: `count count-${entry.key}` });
-    item.appendChild(el("span", { className: "count-label", text: `${entry.label}: ` }));
-    item.appendChild(el("span", { className: "count-value", text: String(entry.value) }));
-    counts.appendChild(item);
-  }
-  section.appendChild(counts);
-
-  const availability = logic.runActions(run.status);
-  const actionBar = el("p", { className: "run-actions" });
-  for (const action of ["pause", "resume", "cancel"] as const) {
-    if (availability[action] !== true) continue;
-    actionBar.appendChild(
-      button(logic.runActionLabel(action), {
-        className: `run-action run-action-${action}`,
-        onClick: () => options.onAction(action),
-      }),
-    );
-    const span = errorSpan(options.errors.get(`run:${action}`));
-    if (span !== null) actionBar.appendChild(span);
-  }
-  if (actionBar.childElementCount > 0) section.appendChild(actionBar);
-
-  const resultsLine = el("p", { className: "results" });
-  resultsLine.appendChild(
-    el("a", {
-      className: "results-link",
-      text: "Download results.csv",
-      attrs: { href: logic.resultsCsvPath(run.id) },
-    }),
-  );
-  section.appendChild(resultsLine);
-  return section;
-}
-
-export interface RecordsTableOptions {
-  records: readonly RecordRow[];
-  expanded: ReadonlySet<string>;
-  transitionsOf: (recordId: string) => readonly Transition[];
-  confirmed: ReadonlyMap<string, boolean>;
-  operatorId: string | null;
-  errors: ReadonlyMap<string, string>;
-  onToggle: (recordId: string) => void;
-  onConfirm: (recordId: string, checked: boolean) => void;
-  onAction: (recordId: string, action: logic.RecordAction) => void;
-}
-
-const RECORD_COLUMNS = 5;
-
-/** Row key, state, reason, attempts — and a row that expands to show its transitions. */
-export function renderRecordsTable(options: RecordsTableOptions): HTMLElement {
-  const section = el("section", { className: "records" });
-  section.appendChild(el("h2", { text: "Records" }));
-  if (options.records.length === 0) {
-    section.appendChild(el("p", { className: "muted", text: "This run has no records yet." }));
-    return section;
-  }
-  const table = el("table", { className: "records-table" });
-  const head = el("tr");
-  for (const label of ["Record", "State", "Reason", "Attempts", "Actions"]) {
-    head.appendChild(el("th", { text: label }));
-  }
-  const thead = el("thead");
-  thead.appendChild(head);
-  table.appendChild(thead);
-  const tbody = el("tbody");
-  for (const record of options.records) {
-    tbody.appendChild(renderRecordRow(record, options));
-    const transitionRow = renderTransitionsRow(record, options);
-    if (transitionRow !== null) tbody.appendChild(transitionRow);
-  }
-  table.appendChild(tbody);
-  section.appendChild(table);
-  return section;
-}
-
-function renderRecordRow(record: RecordRow, options: RecordsTableOptions): HTMLTableRowElement {
-  const gate = logic.actionGate({
-    state: record.state,
-    commitAttempted: record.commit_attempted,
-    confirmed: options.confirmed.get(record.id) === true,
-    operatorId: options.operatorId,
-  });
-  const row = el("tr", { className: `record record-${record.state}`, attrs: { "data-record-id": record.id } });
-
-  const keyCell = el("td", { className: "record-key" });
-  const isExpanded = options.expanded.has(record.id);
-  keyCell.appendChild(
-    button(isExpanded ? "Hide transitions" : "Transitions", {
-      className: "record-toggle",
-      onClick: () => options.onToggle(record.id),
-    }),
-  );
-  // A record key comes from the operator's CSV: untrusted text, so textContent only.
-  keyCell.appendChild(el("span", { className: "record-key-value", text: record.record_key }));
-  row.appendChild(keyCell);
-
-  row.appendChild(el("td", { className: "record-state", text: logic.humanizeStatus(record.state) }));
-  row.appendChild(el("td", { className: "record-reason", text: textOr(record.reason, "—") }));
-  row.appendChild(
-    el("td", { className: "record-attempts", text: `${record.attempts} / ${record.max_attempts}` }),
-  );
-
-  const actions = el("td", { className: "record-actions" });
-  if (gate.shown === false) {
-    actions.appendChild(el("span", { className: "muted", text: "No action" }));
-  } else {
-    if (gate.needsConfirmation) {
-      const label = el("label", { className: "destination-check" });
-      const box = el("input", { className: "destination-check-box" });
-      box.type = "checkbox";
-      // Never pre-ticked: this is the one click that can bypass the duplicate protection.
-      box.checked = options.confirmed.get(record.id) === true;
-      box.addEventListener("change", () => options.onConfirm(record.id, box.checked));
-      label.appendChild(box);
-      label.appendChild(el("span", { className: "destination-check-label", text: logic.DESTINATION_CHECK_LABEL }));
-      actions.appendChild(label);
-    }
-    actions.appendChild(
-      button("Re-queue", {
-        className: "record-requeue",
-        disabled: gate.disabled,
-        onClick: () => options.onAction(record.id, "requeue"),
-      }),
-    );
-    actions.appendChild(
-      button("Dismiss", {
-        className: "record-dismiss",
-        disabled: gate.disabled,
-        onClick: () => options.onAction(record.id, "dismiss"),
-      }),
-    );
-    for (const action of ["requeue", "dismiss"] as const) {
-      const span = errorSpan(options.errors.get(`${record.id}:${action}`));
-      if (span !== null) actions.appendChild(span);
-    }
-  }
-  row.appendChild(actions);
-
-  return row;
-}
-
-/** The second row an expanded record shows: its transitions, or a plain sentence when there are none. */
-function renderTransitionsRow(
-  record: RecordRow,
-  options: RecordsTableOptions,
-): HTMLTableRowElement | null {
-  if (options.expanded.has(record.id) === false) return null;
-  const detailRow = el("tr", { className: "record-transitions-row" });
-  const cell = el("td", { className: "record-transitions", attrs: { colspan: String(RECORD_COLUMNS) } });
-  const transitions = options.transitionsOf(record.id);
-  if (transitions.length === 0) {
-    cell.appendChild(el("p", { className: "muted", text: "No transitions recorded yet." }));
-  } else {
-    const inner = el("table", { className: "transitions-table" });
-    const innerHead = el("tr");
-    for (const label of ["From", "To", "Reason", "Actor", "At"]) {
-      innerHead.appendChild(el("th", { text: label }));
-    }
-    const innerThead = el("thead");
-    innerThead.appendChild(innerHead);
-    inner.appendChild(innerThead);
-    const innerBody = el("tbody");
-    for (const transition of transitions) {
-      const line = el("tr", { className: "transition" });
-      line.appendChild(el("td", { text: textOr(transition.from_state, "—") }));
-      line.appendChild(el("td", { text: transition.to_state }));
-      line.appendChild(el("td", { text: textOr(transition.reason, "—") }));
-      line.appendChild(el("td", { text: textOr(transition.actor, "—") }));
-      line.appendChild(el("td", { text: transition.at }));
-      innerBody.appendChild(line);
-    }
-    inner.appendChild(innerBody);
-    cell.appendChild(inner);
-  }
-  detailRow.appendChild(cell);
-  return detailRow;
-}
-
-export interface ApprovalsOptions {
-  approvals: readonly ApprovalRequest[];
-  operatorId: string | null;
-  errors: ReadonlyMap<string, string>;
-  onDecision: (requestId: string, decision: ApprovalDecision) => void;
-}
-
-/** Each open request, with Approve and Reject. */
-export function renderApprovals(options: ApprovalsOptions): HTMLElement {
-  const section = el("section", { className: "approvals" });
-  section.appendChild(el("h2", { text: "Approvals" }));
-  if (options.approvals.length === 0) {
-    section.appendChild(el("p", { className: "muted", text: "No open approval requests." }));
-    return section;
-  }
-  for (const approval of options.approvals) {
-    const card = el("article", { className: "approval", attrs: { "data-approval-id": approval.id } });
-    card.appendChild(el("h3", { text: `Approval ${approval.id}` }));
-    card.appendChild(
-      el("p", {
-        className: "approval-what",
-        text: `${logic.humanizeToken(approval.kind)} · step ${approval.step_id} · record ${approval.run_record_id}`,
-      }),
-    );
-    const values = el("ul", { className: "approval-values" });
-    const shown = approval.shown ?? {};
-    for (const [key, value] of Object.entries(shown)) {
-      values.appendChild(el("li", { text: `${key}: ${describeValue(value)}` }));
-    }
-    card.appendChild(values);
-
-    const bar = el("p", { className: "approval-actions" });
-    for (const decision of ["approved", "rejected"] as const) {
-      const label = decision === "approved" ? "Approve" : "Reject";
-      bar.appendChild(
-        button(label, {
-          className: `approval-decision approval-${decision}`,
-          disabled: options.operatorId === null,
-          onClick: () => options.onDecision(approval.id, decision),
-        }),
-      );
-      const span = errorSpan(options.errors.get(`approval:${approval.id}:${decision}`));
-      if (span !== null) bar.appendChild(span);
-    }
-    if (options.operatorId === null) {
-      bar.appendChild(
-        el("span", {
-          className: "muted operator-note",
-          text: "Disabled: answering an approval has to record who decided, and PROCESSLENS_OPERATOR_ID is not set.",
-        }),
-      );
-    }
-    card.appendChild(bar);
-    section.appendChild(card);
-  }
-  return section;
-}
diff --git a/apps/web/tests/api.test.ts b/apps/web/tests/api.test.ts
new file mode 100644
index 0000000..5b7a0c6
--- /dev/null
+++ b/apps/web/tests/api.test.ts
@@ -0,0 +1,108 @@
+/** The API client: a good read, the API's own refusal text, and a body that is sent as sent. */
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { ApiError, apiGet, apiPost, errorText } from "../src/lib/api";
+import { callsTo, createFetchStub, type FetchStub } from "./helpers";
+
+let stub: FetchStub;
+
+afterEach(() => {
+  stub.restore();
+});
+
+describe("apiGet", () => {
+  it("reads the JSON the API sends", async () => {
+    stub = createFetchStub({ "/api/v1/operator": { body: { operator_id: "abc" } } });
+
+    await expect(apiGet<{ operator_id: string }>("/api/v1/operator")).resolves.toEqual({
+      operator_id: "abc",
+    });
+    expect(callsTo(stub, "/api/v1/operator")).toBe(1);
+  });
+
+  it("throws the API's own detail text, with its status", async () => {
+    stub = createFetchStub({
+      "/api/v1/records/rec-1/requeue": {
+        status: 409,
+        body: { detail: "a commit was attempted, so a person must confirm the destination" },
+      },
+    });
+
+    const failure = await apiGet("/api/v1/records/rec-1/requeue").catch((error: unknown) => error);
+
+    expect(failure).toBeInstanceOf(ApiError);
+    expect((failure as ApiError).status).toBe(409);
+    expect((failure as ApiError).detail).toBe(
+      "a commit was attempted, so a person must confirm the destination",
+    );
+    expect(errorText(failure)).toBe(
+      "a commit was attempted, so a person must confirm the destination",
+    );
+  });
+
+  it("has a sentence of its own when the API sends no detail", async () => {
+    stub = createFetchStub({ "/api/v1/tasks": { status: 500, body: {} } });
+
+    const failure = (await apiGet("/api/v1/tasks").catch((error: unknown) => error)) as ApiError;
+
+    expect(failure.status).toBe(500);
+    expect(failure.detail).toContain("HTTP 500");
+  });
+
+  it("says it could not reach the API when the call itself fails", async () => {
+    stub = createFetchStub({
+      "/api/v1/tasks": () => {
+        throw new Error("connection refused");
+      },
+    });
+
+    const failure = (await apiGet("/api/v1/tasks").catch((error: unknown) => error)) as ApiError;
+
+    expect(failure).toBeInstanceOf(ApiError);
+    expect(failure.status).toBe(0);
+    expect(failure.detail).toBe("Could not reach the API.");
+  });
+});
+
+describe("apiPost", () => {
+  it("sends the body as JSON and reads the answer", async () => {
+    stub = createFetchStub({
+      "/api/v1/records/rec-1/requeue": { body: { record_id: "rec-1", state: "pending" } },
+    });
+
+    const answer = await apiPost<{ state: string }>("/api/v1/records/rec-1/requeue", {
+      destination_checked_by: "operator-1",
+    });
+
+    expect(answer.state).toBe("pending");
+    expect(stub.requests).toEqual([
+      {
+        method: "POST",
+        path: "/api/v1/records/rec-1/requeue",
+        body: { destination_checked_by: "operator-1" },
+      },
+    ]);
+  });
+
+  it("sends no body when there is nothing to send", async () => {
+    stub = createFetchStub({ "/api/v1/records/rec-1/dismiss": { body: { state: "skipped" } } });
+
+    await apiPost("/api/v1/records/rec-1/dismiss");
+
+    expect(stub.requests[0]?.body).toBeNull();
+  });
+});
+
+describe("errorText", () => {
+  it("falls back to one plain sentence for anything else", () => {
+    expect(errorText(new Error("boom"))).toBe("boom");
+    expect(errorText(undefined)).toBe("Something went wrong.");
+    expect(errorText("see the log")).toBe("Something went wrong.");
+  });
+});
+
+beforeEach(() => {
+  // Every test builds its own stub; this keeps the type checker honest about the shared variable.
+  stub = createFetchStub({});
+});
diff --git a/apps/web/tests/commitGate.test.ts b/apps/web/tests/commitGate.test.ts
deleted file mode 100644
index bd491cf..0000000
--- a/apps/web/tests/commitGate.test.ts
+++ /dev/null
@@ -1,193 +0,0 @@
-/**
- * The commit-attempted confirmation: the one click that can put a record back in front of the
- * ledger's duplicate protection, so it is never one click.
- */
-
-import { describe, expect, it } from "vitest";
-import { mountApp } from "../src/app";
-import * as logic from "../src/logic";
-import * as view from "../src/view";
-import type { RecordRow } from "../src/types";
-import { OPERATOR_ID, callsTo, createFetchStub, sampleRecord, sampleRunDetail, settle } from "./helpers";
-
-function renderTable(
-  container: HTMLElement,
-  records: readonly RecordRow[],
-  confirmed: Map<string, boolean>,
-  operatorId: string | null = OPERATOR_ID,
-): void {
-  view.clearNode(container);
-  container.appendChild(
-    view.renderRecordsTable({
-      records,
-      expanded: new Set<string>(),
-      transitionsOf: () => [],
-      confirmed,
-      operatorId,
-      errors: new Map<string, string>(),
-      onToggle: () => {},
-      onConfirm: (recordId, checked) => {
-        confirmed.set(recordId, checked);
-      },
-      onAction: () => {},
-    }),
-  );
-}
-
-function buttonWith(container: HTMLElement, selector: string): HTMLButtonElement {
-  const node = container.querySelector<HTMLButtonElement>(selector);
-  if (node === null) throw new Error(`no button matching ${selector}`);
-  return node;
-}
-
-function checkbox(container: HTMLElement): HTMLInputElement {
-  const node = container.querySelector<HTMLInputElement>(".destination-check-box");
-  if (node === null) throw new Error("no destination-check checkbox");
-  return node;
-}
-
-function tick(box: HTMLInputElement, checked: boolean): void {
-  box.checked = checked;
-  box.dispatchEvent(new Event("change"));
-}
-
-describe("the destination check gates a commit-attempted record", () => {
-  it("disables both buttons until the unticked confirmation is ticked, and again once it is cleared", () => {
-    const record = sampleRecord({ state: "parked", commit_attempted: true });
-    const confirmed = new Map<string, boolean>();
-    const container = document.createElement("div");
-    document.body.appendChild(container);
-
-    renderTable(container, [record], confirmed);
-    const first = checkbox(container);
-    expect(first.checked).toBe(false);
-    expect(container.querySelector(".destination-check-label")?.textContent).toBe(
-      logic.DESTINATION_CHECK_LABEL,
-    );
-    expect(buttonWith(container, ".record-requeue").disabled).toBe(true);
-    expect(buttonWith(container, ".record-dismiss").disabled).toBe(true);
-
-    tick(first, true);
-    renderTable(container, [record], confirmed);
-    expect(checkbox(container).checked).toBe(true);
-    expect(buttonWith(container, ".record-requeue").disabled).toBe(false);
-    expect(buttonWith(container, ".record-dismiss").disabled).toBe(false);
-
-    tick(checkbox(container), false);
-    renderTable(container, [record], confirmed);
-    expect(buttonWith(container, ".record-requeue").disabled).toBe(true);
-    expect(buttonWith(container, ".record-dismiss").disabled).toBe(true);
-  });
-
-  it("asks nothing extra of a record that never reached a commit", () => {
-    const record = sampleRecord({ state: "failed", commit_attempted: false });
-    const container = document.createElement("div");
-    document.body.appendChild(container);
-
-    renderTable(container, [record], new Map<string, boolean>());
-    expect(container.querySelector(".destination-check-box")).toBeNull();
-    expect(buttonWith(container, ".record-requeue").disabled).toBe(false);
-    expect(buttonWith(container, ".record-dismiss").disabled).toBe(false);
-  });
-
-  it("stays disabled while the API has no operator id to send", () => {
-    const record = sampleRecord({ state: "parked", commit_attempted: true });
-    const confirmed = new Map<string, boolean>([["record-1", true]]);
-    const container = document.createElement("div");
-    document.body.appendChild(container);
-
-    renderTable(container, [record], confirmed, null);
-    expect(buttonWith(container, ".record-requeue").disabled).toBe(true);
-    expect(buttonWith(container, ".record-dismiss").disabled).toBe(true);
-  });
-
-  it("sends destination_checked_by only after the tick, and ticks nothing by itself", async () => {
-    const record = sampleRecord({ state: "parked", commit_attempted: true });
-    const { fetchImpl, calls } = createFetchStub((call) => {
-      if (call.path === "/api/v1/operator") return { status: 200, body: { operator_id: OPERATOR_ID } };
-      if (call.path === "/api/v1/runs/run-1") return { status: 200, body: sampleRunDetail() };
-      if (call.path === "/api/v1/runs/run-1/records") return { status: 200, body: [record] };
-      if (call.path === "/api/v1/runs/run-1/approvals") return { status: 200, body: [] };
-      if (call.path.startsWith("/api/v1/runs/run-1/transitions")) return { status: 200, body: [] };
-      if (call.path === "/api/v1/records/record-1/dismiss") {
-        return { status: 200, body: { record_id: "record-1", state: "skipped" } };
-      }
-      return { status: 404, body: { detail: `unexpected ${call.method} ${call.path}` } };
-    });
-
-    const root = document.createElement("div");
-    document.body.appendChild(root);
-    const app = mountApp(root, { fetchImpl });
-    await app.openRun("run-1");
-
-    const dismiss = root.querySelector<HTMLButtonElement>(".record-dismiss");
-    expect(dismiss).not.toBeNull();
-    expect(dismiss?.disabled).toBe(true);
-
-    dismiss?.click();
-    await settle();
-    expect(callsTo(calls, "POST", "/api/v1/records/record-1/dismiss")).toHaveLength(0);
-
-    const box = root.querySelector<HTMLInputElement>(".destination-check-box");
-    expect(box).not.toBeNull();
-    if (box === null) return;
-    tick(box, true);
-
-    const enabled = root.querySelector<HTMLButtonElement>(".record-dismiss");
-    expect(enabled?.disabled).toBe(false);
-    enabled?.click();
-    await settle();
-
-    const posts = callsTo(calls, "POST", "/api/v1/records/record-1/dismiss");
-    expect(posts).toHaveLength(1);
-    expect(posts[0]?.body).toEqual({ destination_checked_by: OPERATOR_ID });
-    app.destroy();
-  });
-});
-
-describe("the gate itself", () => {
-  it("names both requirements and no more", () => {
-    const gate = logic.actionGate({
-      state: "parked",
-      commitAttempted: true,
-      confirmed: false,
-      operatorId: OPERATOR_ID,
-    });
-    expect(gate.needsConfirmation).toBe(true);
-    expect(gate.needsOperator).toBe(true);
-    expect(gate.disabled).toBe(true);
-    expect(gate.shown).toBe(true);
-  });
-
-  it("leaves a verified record alone", () => {
-    const gate = logic.actionGate({
-      state: "verified",
-      commitAttempted: true,
-      confirmed: true,
-      operatorId: OPERATOR_ID,
-    });
-    expect(gate.shown).toBe(false);
-    expect(logic.recordActions("verified")).toEqual({ requeue: false, dismiss: false });
-  });
-});
-
-describe("the request body", () => {
-  it("carries the operator id only when a commit was attempted and the check was confirmed", () => {
-    expect(
-      logic.actionBody({
-        commitAttempted: false,
-        confirmed: false,
-        operatorId: OPERATOR_ID,
-      }),
-    ).toEqual({});
-    expect(
-      logic.actionBody({ commitAttempted: true, confirmed: true, operatorId: OPERATOR_ID }),
-    ).toEqual({ destination_checked_by: OPERATOR_ID });
-    expect(() =>
-      logic.actionBody({ commitAttempted: true, confirmed: false, operatorId: OPERATOR_ID }),
-    ).toThrow();
-    expect(() =>
-      logic.actionBody({ commitAttempted: true, confirmed: true, operatorId: null }),
-    ).toThrow();
-  });
-});
diff --git a/apps/web/tests/errorDetail.test.ts b/apps/web/tests/errorDetail.test.ts
deleted file mode 100644
index 5031ca2..0000000
--- a/apps/web/tests/errorDetail.test.ts
+++ /dev/null
@@ -1,150 +0,0 @@
-/**
- * Refusals: a 409's `detail` text appears next to the button that caused it, the page never retries
- * on its own, and a 503 from the operator endpoint disables what needs the id.
- */
-
-import { describe, expect, it } from "vitest";
-import { mountApp } from "../src/app";
-import type { RecordRow } from "../src/types";
-import {
-  OPERATOR_ID,
-  callsTo,
-  createFetchStub,
-  sampleApproval,
-  sampleRecord,
-  sampleRunDetail,
-  settle,
-  type RecordedCall,
-} from "./helpers";
-
-const CONFLICT = "record record-1 is parked and commit_attempted needs a destination check";
-const OPERATOR_503 = "PROCESSLENS_OPERATOR_ID is not set";
-
-function runResponses(
-  record: RecordRow,
-  extra?: (call: RecordedCall) => { status: number; body: unknown } | undefined,
-) {
-  return (call: RecordedCall): { status: number; body: unknown } => {
-    const handled = extra?.(call);
-    if (handled !== undefined) return handled;
-    if (call.path === "/api/v1/operator") return { status: 200, body: { operator_id: OPERATOR_ID } };
-    if (call.path === "/api/v1/runs/run-1") return { status: 200, body: sampleRunDetail() };
-    if (call.path === "/api/v1/runs/run-1/records") return { status: 200, body: [record] };
-    if (call.path === "/api/v1/runs/run-1/approvals") return { status: 200, body: [sampleApproval()] };
-    if (call.path.startsWith("/api/v1/runs/run-1/transitions")) return { status: 200, body: [] };
-    return { status: 404, body: { detail: `unexpected ${call.method} ${call.path}` } };
-  };
-}
-
-describe("a refused request shows the API's detail text next to the button", () => {
-  it("shows a 409 from Dismiss beside the Dismiss button and does not retry", async () => {
-    const record = sampleRecord({ state: "parked", commit_attempted: false });
-    const { fetchImpl, calls } = createFetchStub((call) => {
-      const handled = runResponses(record)(call);
-      if (handled.status === 404 && call.path === "/api/v1/records/record-1/dismiss") {
-        return { status: 409, body: { detail: CONFLICT } };
-      }
-      return handled;
-    });
-
-    const root = document.createElement("div");
-    document.body.appendChild(root);
-    const app = mountApp(root, { fetchImpl });
-    await app.openRun("run-1");
-
-    const dismiss = root.querySelector<HTMLButtonElement>(".record-dismiss");
-    expect(dismiss).not.toBeNull();
-    dismiss?.click();
-    await settle();
-
-    const cell = root.querySelector<HTMLElement>(".record-actions");
-    const error = cell?.querySelector<HTMLElement>(".action-error");
-    expect(error?.textContent).toBe(CONFLICT);
-    // "next to the button": the same cell the Dismiss button lives in.
-    expect(root.querySelector<HTMLButtonElement>(".record-dismiss")?.closest("td")).toBe(cell);
-
-    const before = callsTo(calls, "POST", "/api/v1/records/record-1/dismiss").length;
-    expect(before).toBe(1);
-    await settle();
-    expect(callsTo(calls, "POST", "/api/v1/records/record-1/dismiss").length).toBe(1);
-    app.destroy();
-  });
-
-  it("shows a 409 from Pause beside the Pause button", async () => {
-    const record = sampleRecord({ state: "verified", commit_attempted: false });
-    const { fetchImpl } = createFetchStub((call) => {
-      if (call.path === "/api/v1/runs/run-1/pause") {
-        return { status: 409, body: { detail: "run run-1 is completed" } };
-      }
-      return runResponses(record)(call);
-    });
-
-    const root = document.createElement("div");
-    document.body.appendChild(root);
-    const app = mountApp(root, { fetchImpl });
-    await app.openRun("run-1");
-
-    root.querySelector<HTMLButtonElement>(".run-action-pause")?.click();
-    await settle();
-
-    const bar = root.querySelector<HTMLElement>(".run-actions");
-    expect(bar?.querySelector(".action-error")?.textContent).toBe("run run-1 is completed");
-    expect(root.querySelector<HTMLButtonElement>(".run-action-pause")?.closest("p")).toBe(bar);
-    app.destroy();
-  });
-});
-
-describe("the operator identity", () => {
-  it("disables approvals and says why when the endpoint answers 503", async () => {
-    const record = sampleRecord({ state: "parked", commit_attempted: true });
-    const { fetchImpl } = createFetchStub((call) => {
-      if (call.path === "/api/v1/operator") return { status: 503, body: { detail: OPERATOR_503 } };
-      return runResponses(record)(call);
-    });
-
-    const root = document.createElement("div");
-    document.body.appendChild(root);
-    const app = mountApp(root, { fetchImpl });
-    await app.openRun("run-1");
-
-    expect(app.status().operatorId).toBeNull();
-    const approve = root.querySelector<HTMLButtonElement>(".approval-approved");
-    const reject = root.querySelector<HTMLButtonElement>(".approval-rejected");
-    expect(approve?.disabled).toBe(true);
-    expect(reject?.disabled).toBe(true);
-    // It refuses to act, and it says why — including the API's own words.
-    const note = root.querySelector<HTMLElement>(".operator-problem");
-    expect(note?.textContent).toContain(OPERATOR_503);
-    expect(root.querySelector<HTMLElement>(".operator-note")?.textContent).toContain(
-      "PROCESSLENS_OPERATOR_ID",
-    );
-    // A commit-attempted record also needs the id, so its buttons stay disabled too.
-    expect(root.querySelector<HTMLButtonElement>(".record-dismiss")?.disabled).toBe(true);
-    app.destroy();
-  });
-
-  it("answers an approval with the API's operator id", async () => {
-    const record = sampleRecord({ state: "verified", commit_attempted: false });
-    const { fetchImpl, calls } = createFetchStub((call) => {
-      if (call.path === "/api/v1/approvals") return { status: 200, body: { ok: true } };
-      return runResponses(record)(call);
-    });
-
-    const root = document.createElement("div");
-    document.body.appendChild(root);
-    const app = mountApp(root, { fetchImpl });
-    await app.openRun("run-1");
-
-    root.querySelector<HTMLButtonElement>(".approval-approved")?.click();
-    await settle();
-
-    const posts = callsTo(calls, "POST", "/api/v1/approvals");
-    expect(posts).toHaveLength(1);
-    expect(posts[0]?.body).toEqual({
-      request_id: "approval-1",
-      decision: "approved",
-      decided_by: OPERATOR_ID,
-    });
-    app.destroy();
-  });
-});
diff --git a/apps/web/tests/helpers.ts b/apps/web/tests/helpers.ts
deleted file mode 100644
index e9255a3..0000000
--- a/apps/web/tests/helpers.ts
+++ /dev/null
@@ -1,138 +0,0 @@
-/** Test-only helpers: a fake `fetch`, recorded calls, and the fixtures the API would send. */
-
-import { vi } from "vitest";
-
-import type { ApprovalRequest, RecordRow, RunDetail, RunSummary, Transition } from "../src/types";
-
-export const OPERATOR_ID = "3f1c4f5e-0000-4000-8000-00000000abcd";
-
-export interface RecordedCall {
-  method: string;
-  path: string;
-  body: unknown;
-}
-
-export interface StubResult {
-  status: number;
-  body: unknown;
-}
-
-export interface FetchStub {
-  fetchImpl: typeof fetch;
-  calls: RecordedCall[];
-}
-
-/** A `Response` good enough for the client: status, ok, and a JSON text body. */
-export function jsonResponse(status: number, body: unknown): Response {
-  return {
-    ok: status >= 200 && status < 300,
-    status,
-    text: async () => (body === undefined ? "" : JSON.stringify(body)),
-  } as unknown as Response;
-}
-
-export function createFetchStub(
-  handler: (call: RecordedCall) => StubResult | Promise<StubResult>,
-): FetchStub {
-  const calls: RecordedCall[] = [];
-  const fetchImpl = async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
-    const rawBody = init?.body;
-    const call: RecordedCall = {
-      method: init?.method ?? "GET",
-      path: typeof input === "string" ? input : String(input),
-      body: typeof rawBody === "string" ? JSON.parse(rawBody) : undefined,
-    };
-    calls.push(call);
-    const result = await handler(call);
-    return jsonResponse(result.status, result.body);
-  };
-  return { fetchImpl: fetchImpl as unknown as typeof fetch, calls };
-}
-
-/** Every call that hit `method` on a path containing `fragment`. */
-export function callsTo(calls: readonly RecordedCall[], method: string, fragment: string): RecordedCall[] {
-  return calls.filter((call) => call.method === method && call.path.includes(fragment));
-}
-
-export function sampleRecord(overrides: Partial<RecordRow> = {}): RecordRow {
-  return {
-    id: "record-1",
-    record_key: "ACME-1",
-    state: "parked",
-    reason: "needs a person",
-    attempts: 1,
-    max_attempts: 3,
-    commit_attempted: false,
-    destination_ref: null,
-    ...overrides,
-  };
-}
-
-export function sampleRunDetail(overrides: Partial<RunDetail> = {}): RunDetail {
-  return {
-    id: "run-1",
-    status: "running",
-    pause_reason: null,
-    counts: { total: 2, verified: 1, skipped: 0, parked: 1, failed: 0, in_progress: 0 },
-    open_approval: null,
-    ...overrides,
-  };
-}
-
-export function sampleRunSummary(overrides: Partial<RunSummary> = {}): RunSummary {
-  return {
-    id: "run-1",
-    status: "running",
-    pause_reason: null,
-    created_at: "2026-01-01T00:00:00Z",
-    recipe_name: "Enrolment recipe",
-    recipe_version: "v3",
-    counts: { verified: 1, parked: 1 },
-    ...overrides,
-  };
-}
-
-export function sampleApproval(overrides: Partial<ApprovalRequest> = {}): ApprovalRequest {
-  return {
-    id: "approval-1",
-    run_record_id: "record-1",
-    step_id: "step-7",
-    kind: "low_confidence",
-    shown: { field: "Name", value: "ACME" },
-    created_at: "2026-01-01T00:00:00Z",
-    ...overrides,
-  };
-}
-
-export function sampleTransition(overrides: Partial<Transition> = {}): Transition {
-  return {
-    id: 1,
-    run_record_id: "record-1",
-    from_state: "in_progress",
-    to_state: "parked",
-    reason: "no match",
-    actor: "worker",
-    at: "2026-01-01T00:00:00Z",
-    ...overrides,
-  };
-}
-
-/** Let the promise chains a click or a tick starts finish.
- *
- * Under a fake clock a real ``setTimeout`` never fires, so a caller that installed one (the polling
- * tests do) would wait for a wall-clock tick that can never come and time out. When fake timers are
- * active this drains microtasks and lets the faked timers run instead; otherwise it yields to the
- * real event loop a few times.
- */
-export async function settle(): Promise<void> {
-  if (vi.isFakeTimers()) {
-    await vi.advanceTimersByTimeAsync(0);
-    for (let i = 0; i < 6; i += 1) {
-      await Promise.resolve();
-    }
-    return;
-  }
-  for (let i = 0; i < 6; i += 1) {
-    await new Promise((resolve) => setTimeout(resolve, 0));
-  }
-}
diff --git a/apps/web/tests/helpers.tsx b/apps/web/tests/helpers.tsx
new file mode 100644
index 0000000..715a38a
--- /dev/null
+++ b/apps/web/tests/helpers.tsx
@@ -0,0 +1,114 @@
+/**
+ * Test-only helpers: the router-wrapping render, a fake `fetch`, and the two ways to look at it.
+ *
+ * Every other test file imports these, so a page test never builds its own router or touches the
+ * real network.
+ */
+
+import { act, render, type RenderResult } from "@testing-library/react";
+import type { ReactElement } from "react";
+import { MemoryRouter } from "react-router-dom";
+
+import { App } from "../src/App";
+
+export interface RecordedRequest {
+  method: string;
+  path: string;
+  body: unknown;
+}
+
+export interface StubResponse {
+  status?: number;
+  body: unknown;
+}
+
+export type StubRoutes = Record<string, StubResponse | ((call: RecordedRequest) => StubResponse)>;
+
+export interface FetchStub {
+  /** The paths asked for, in order. */
+  calls: string[];
+  /** Every request, with its method and its parsed body. */
+  requests: RecordedRequest[];
+  /** Put the real `fetch` back. */
+  restore: () => void;
+}
+
+/** A `Response` good enough for the API client: status, ok, and a JSON text body. */
+export function jsonResponse(status: number, body: unknown): Response {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    text: async () => (body === undefined ? "" : JSON.stringify(body)),
+  } as unknown as Response;
+}
+
+function pick(routes: StubRoutes, path: string): StubRoutes[string] | undefined {
+  const exact = routes[path];
+  if (exact !== undefined) return exact;
+  const prefixes = Object.keys(routes)
+    .filter((key) => path.startsWith(key))
+    .sort((left, right) => right.length - left.length);
+  const longest = prefixes[0];
+  return longest === undefined ? undefined : routes[longest];
+}
+
+/**
+ * Replace `fetch` with a stub that answers from `routes`. A key matches the path exactly, or as the
+ * longest prefix of it, so `/api/v1/runs` also answers `/api/v1/runs/abc`. An unmatched path is a
+ * 404 with the API's own detail shape.
+ */
+export function createFetchStub(routes: StubRoutes = {}): FetchStub {
+  const original = globalThis.fetch;
+  const requests: RecordedRequest[] = [];
+  const calls: string[] = [];
+
+  const stub = async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
+    const raw =
+      typeof input === "string" ? input : input instanceof URL ? input.toString() : String(input);
+    const path = new URL(raw, "http://localhost").pathname;
+    const method = (init?.method ?? "GET").toUpperCase();
+    const rawBody = init?.body;
+    const body: unknown =
+      typeof rawBody === "string" && rawBody !== "" ? (JSON.parse(rawBody) as unknown) : null;
+    const call: RecordedRequest = { method, path, body };
+    requests.push(call);
+    calls.push(path);
+    const entry = pick(routes, path);
+    const answer = entry === undefined ? { body: { detail: "Not found" } } : entry;
+    const resolved = typeof answer === "function" ? answer(call) : answer;
+    return jsonResponse(resolved.status ?? 200, resolved.body);
+  };
+
+  globalThis.fetch = stub as unknown as typeof fetch;
+  return {
+    calls,
+    requests,
+    restore: () => {
+      globalThis.fetch = original;
+    },
+  };
+}
+
+/** How many times a path was asked for. */
+export function callsTo(stub: FetchStub, path: string): number {
+  return stub.calls.filter((call) => call === path).length;
+}
+
+/** Let the queue of promises and the pending renders finish, so assertions see the settled page. */
+export async function settle(rounds = 3): Promise<void> {
+  for (let round = 0; round < rounds; round += 1) {
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    });
+  }
+}
+
+/** Render the whole app, at one path, inside a router. */
+export function renderApp(path = "/"): RenderResult {
+  const element: ReactElement = (
+    <MemoryRouter initialEntries={[path]}>
+      <App />
+    </MemoryRouter>
+  );
+  return render(element);
+}
diff --git a/apps/web/tests/injection.test.ts b/apps/web/tests/injection.test.ts
deleted file mode 100644
index abb7609..0000000
--- a/apps/web/tests/injection.test.ts
+++ /dev/null
@@ -1,101 +0,0 @@
-/**
- * Record values come from the operator's CSV, so they are untrusted text. A value that looks like
- * markup must land in the document as characters, never as an element.
- */
-
-import { describe, expect, it } from "vitest";
-import { mountApp } from "../src/app";
-import * as logic from "../src/logic";
-import * as view from "../src/view";
-import type { RecordRow } from "../src/types";
-import { OPERATOR_ID, createFetchStub, sampleRecord, sampleRunDetail } from "./helpers";
-
-const HOSTILE = '<img src=x onerror=alert(1)>ACME-1';
-
-function table(record: RecordRow): HTMLElement {
-  return view.renderRecordsTable({
-    records: [record],
-    expanded: new Set<string>([record.id]),
-    transitionsOf: () => [
-      {
-        id: 1,
-        run_record_id: record.id,
-        from_state: "<b>in_progress</b>",
-        to_state: "parked",
-        reason: HOSTILE,
-        actor: HOSTILE,
-        at: "2026-01-01T00:00:00Z",
-      },
-    ],
-    confirmed: new Map<string, boolean>(),
-    operatorId: OPERATOR_ID,
-    errors: new Map<string, string>(),
-    onToggle: () => {},
-    onConfirm: () => {},
-    onAction: () => {},
-  });
-}
-
-describe("untrusted record values are rendered as text", () => {
-  it("shows a record key containing markup as characters, with no element made from it", () => {
-    const node = table(sampleRecord({ record_key: HOSTILE, reason: HOSTILE }));
-
-    expect(node.querySelectorAll("img")).toHaveLength(0);
-    expect(node.querySelectorAll("script")).toHaveLength(0);
-    expect(node.querySelector(".record-key-value")?.textContent).toBe(HOSTILE);
-    expect(node.querySelector(".record-reason")?.textContent).toBe(HOSTILE);
-    expect(node.querySelector(".record-key-value")?.children).toHaveLength(0);
-  });
-
-  it("treats a transition's reason and actor the same way", () => {
-    const node = table(sampleRecord({ record_key: "ACME-1" }));
-
-    expect(node.querySelectorAll("img")).toHaveLength(0);
-    const cells = Array.from(node.querySelectorAll(".transition td")).map((cell) => cell.textContent);
-    expect(cells).toContain(HOSTILE);
-  });
-
-  it("never writes markup through the element helper", () => {
-    const node = view.el("span", { text: HOSTILE });
-    expect(node.querySelector("img")).toBeNull();
-    expect(node.textContent).toBe(HOSTILE);
-    expect(node.innerHTML).toBe("&lt;img src=x onerror=alert(1)&gt;ACME-1");
-  });
-
-  it("keeps the page host element free of markup when the API sends it, and says the count", async () => {
-    const hostileRun = sampleRunDetail({ id: "run-1", status: "paused", pause_reason: "challenge" });
-    const { fetchImpl } = createFetchStub((call) => {
-      if (call.path === "/api/v1/operator") return { status: 200, body: { operator_id: OPERATOR_ID } };
-      if (call.path === "/api/v1/runs/run-1") return { status: 200, body: hostileRun };
-      if (call.path === "/api/v1/runs/run-1/records") {
-        return { status: 200, body: [sampleRecord({ record_key: HOSTILE, state: "parked" })] };
-      }
-      if (call.path === "/api/v1/runs/run-1/approvals") {
-        return {
-          status: 200,
-          body: [
-            {
-              id: "approval-1",
-              run_record_id: "record-1",
-              step_id: "step-7",
-              kind: "low_confidence",
-              shown: { note: HOSTILE },
-              created_at: "2026-01-01T00:00:00Z",
-            },
-          ],
-        };
-      }
-      return { status: 404, body: { detail: "unexpected" } };
-    });
-
-    const root = document.createElement("div");
-    document.body.appendChild(root);
-    const app = mountApp(root, { fetchImpl });
-    await app.openRun("run-1");
-
-    expect(root.querySelectorAll("img")).toHaveLength(0);
-    expect(root.textContent).toContain(HOSTILE);
-    expect(logic.humanizePauseReason("challenge")).toContain("bound tab");
-    app.destroy();
-  });
-});
diff --git a/apps/web/tests/polling.test.ts b/apps/web/tests/polling.test.ts
deleted file mode 100644
index 77173ea..0000000
--- a/apps/web/tests/polling.test.ts
+++ /dev/null
@@ -1,116 +0,0 @@
-/** Polling: every 2 seconds while the run is open, and not one tick after it is finished. */
-
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { mountApp } from "../src/app";
-import * as logic from "../src/logic";
-import { OPERATOR_ID, createFetchStub, sampleRecord, sampleRunDetail, settle } from "./helpers";
-import type { RunDetail } from "../src/types";
-
-describe("the interval", () => {
-  it("is two seconds, and stops as soon as the run stops being open", () => {
-    const ticks: number[] = [];
-    let status = "running";
-    const poller = logic.createPoller({
-      onTick: () => {
-        ticks.push(Date.now());
-      },
-      shouldContinue: () => logic.isOpenStatus(status),
-    });
-    expect(logic.POLL_INTERVAL_MS).toBe(2000);
-    expect(poller.isRunning()).toBe(false);
-    poller.start();
-    expect(poller.isRunning()).toBe(true);
-    poller.start(); // idempotent: one interval, not two
-    poller.stop();
-    expect(poller.isRunning()).toBe(false);
-    expect(ticks).toEqual([]);
-    expect(status).toBe("running");
-  });
-
-  it("knows which statuses are open", () => {
-    for (const open of ["queued", "running", "paused"]) {
-      expect(logic.shouldPoll(open)).toBe(true);
-    }
-    for (const finished of ["completed", "cancelled", "failed"]) {
-      expect(logic.shouldPoll(finished)).toBe(false);
-    }
-    expect(logic.shouldPoll(null)).toBe(false);
-  });
-});
-
-describe("the page's poll", () => {
-  beforeEach(() => {
-    vi.useFakeTimers();
-  });
-
-  afterEach(() => {
-    vi.useRealTimers();
-  });
-
-  it("ticks every two seconds while the run is open and stops once it is finished", async () => {
-    let run: RunDetail = sampleRunDetail({ status: "running" });
-    let detailCalls = 0;
-    const { fetchImpl } = createFetchStub((call) => {
-      if (call.path === "/api/v1/operator") return { status: 200, body: { operator_id: OPERATOR_ID } };
-      if (call.path === "/api/v1/runs/run-1") {
-        detailCalls += 1;
-        return { status: 200, body: run };
-      }
-      if (call.path === "/api/v1/runs/run-1/records") {
-        return { status: 200, body: [sampleRecord({ state: "verified", commit_attempted: false })] };
-      }
-      if (call.path === "/api/v1/runs/run-1/approvals") return { status: 200, body: [] };
-      return { status: 404, body: { detail: `unexpected ${call.path}` } };
-    });
-
-    const root = document.createElement("div");
-    document.body.appendChild(root);
-    const app = mountApp(root, { fetchImpl });
-    await app.openRun("run-1");
-    expect(app.status().polling).toBe(true);
-    const afterFirstLoad = detailCalls;
-
-    await vi.advanceTimersByTimeAsync(2000);
-    await settle();
-    expect(app.status().polling).toBe(true);
-    expect(detailCalls).toBeGreaterThan(afterFirstLoad);
-
-    const afterOneTick = detailCalls;
-    await vi.advanceTimersByTimeAsync(2000);
-    await settle();
-    expect(detailCalls).toBeGreaterThan(afterOneTick);
-
-    // The API now reports the run as finished: the next refresh must stop the poll for good.
-    run = sampleRunDetail({ status: "completed" });
-    await vi.advanceTimersByTimeAsync(2000);
-    await settle();
-    expect(app.status().runStatus).toBe("completed");
-    expect(app.status().polling).toBe(false);
-
-    const afterFinish = detailCalls;
-    await vi.advanceTimersByTimeAsync(10_000);
-    await settle();
-    expect(detailCalls).toBe(afterFinish);
-    expect(app.status().polling).toBe(false);
-    app.destroy();
-  });
-
-  it("does not poll a run that is already finished", async () => {
-    const { fetchImpl } = createFetchStub((call) => {
-      if (call.path === "/api/v1/operator") return { status: 200, body: { operator_id: OPERATOR_ID } };
-      if (call.path === "/api/v1/runs/run-1") {
-        return { status: 200, body: sampleRunDetail({ status: "failed" }) };
-      }
-      if (call.path === "/api/v1/runs/run-1/records") return { status: 200, body: [] };
-      if (call.path === "/api/v1/runs/run-1/approvals") return { status: 200, body: [] };
-      return { status: 404, body: { detail: "unexpected" } };
-    });
-
-    const root = document.createElement("div");
-    document.body.appendChild(root);
-    const app = mountApp(root, { fetchImpl });
-    await app.openRun("run-1");
-    expect(app.status().polling).toBe(false);
-    app.destroy();
-  });
-});
diff --git a/apps/web/tests/router.test.tsx b/apps/web/tests/router.test.tsx
new file mode 100644
index 0000000..af6c5e7
--- /dev/null
+++ b/apps/web/tests/router.test.tsx
@@ -0,0 +1,84 @@
+/** The router: every sidebar route lands on a real page, and no page is ever blank. */
+
+import { cleanup, screen } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { createFetchStub, renderApp, settle, type FetchStub } from "./helpers";
+
+/** Every path the sidebar can reach. */
+const PATHS = [
+  "/",
+  "/needs-help",
+  "/tasks",
+  "/tasks/w-1",
+  "/runs",
+  "/runs/run-1",
+  "/teach",
+  "/spreadsheets",
+  "/documents",
+  "/saved-answers",
+  "/apps",
+  "/settings",
+  "/help",
+];
+
+/** The pages this ticket does not build: each shows the designed empty state. */
+const COMING_SOON = [
+  "/teach",
+  "/spreadsheets",
+  "/documents",
+  "/saved-answers",
+  "/apps",
+  "/settings",
+  "/help",
+];
+
+let stub: FetchStub;
+
+beforeEach(() => {
+  stub = createFetchStub({
+    "/api/v1/needs-help": { body: [] },
+    "/api/v1/executor/session": { body: { attached: false } },
+    "/api/v1/tasks": { body: [] },
+  });
+});
+
+afterEach(() => {
+  stub.restore();
+  cleanup();
+});
+
+describe("the router", () => {
+  it("renders every sidebar path with a page title and at most one primary action", async () => {
+    for (const path of PATHS) {
+      const view = renderApp(path);
+      await settle(1);
+
+      expect(screen.getByRole("heading", { level: 2 }).textContent, path).toBeTruthy();
+      expect(document.querySelectorAll(".btn.primary").length, path).toBeLessThanOrEqual(1);
+      expect(screen.getByRole("main").textContent ?? "", path).not.toBe("");
+
+      view.unmount();
+    }
+  });
+
+  it("gives a detail route its own page rather than the list beside it", async () => {
+    const view = renderApp("/runs/run-1");
+    await settle(1);
+
+    expect(screen.getByRole("heading", { level: 2 }).textContent).toBe("Run");
+    view.unmount();
+  });
+
+  it("shows a designed empty state on every page this ticket does not build", async () => {
+    for (const path of COMING_SOON) {
+      const view = renderApp(path);
+      await settle(1);
+
+      expect(screen.getAllByText("Coming soon").length, path).toBeGreaterThan(0);
+      expect(screen.getByText(/will appear here|coming next/i), path).toBeTruthy();
+
+      view.unmount();
+    }
+  });
+});
diff --git a/apps/web/tests/runButtons.test.ts b/apps/web/tests/runButtons.test.ts
deleted file mode 100644
index f4aff96..0000000
--- a/apps/web/tests/runButtons.test.ts
+++ /dev/null
@@ -1,94 +0,0 @@
-/** The run buttons follow the status, and the pause reason is written for a person. */
-
-import { describe, expect, it } from "vitest";
-import * as logic from "../src/logic";
-import * as view from "../src/view";
-import { sampleRunDetail } from "./helpers";
-
-function header(status: string, pauseReason: string | null = null): HTMLElement {
-  return view.renderRunHeader({
-    run: sampleRunDetail({ status, pause_reason: pauseReason }),
-    errors: new Map<string, string>(),
-    onAction: () => {},
-  });
-}
-
-function labels(node: HTMLElement): string[] {
-  return Array.from(node.querySelectorAll("button")).map((buttonNode) => buttonNode.textContent ?? "");
-}
-
-describe("run buttons follow the status", () => {
-  it("offers Pause and Cancel for an open run, and Resume only when it is paused", () => {
-    expect(labels(header("queued"))).toEqual(["Pause", "Cancel"]);
-    expect(labels(header("running"))).toEqual(["Pause", "Cancel"]);
-    expect(labels(header("paused"))).toEqual(["Pause", "Resume", "Cancel"]);
-  });
-
-  it("offers nothing once the run is finished", () => {
-    expect(labels(header("completed"))).toEqual([]);
-    expect(labels(header("cancelled"))).toEqual([]);
-    expect(labels(header("failed"))).toEqual([]);
-  });
-
-  it("says the same thing in logic", () => {
-    expect(logic.runActions("running")).toEqual({ pause: true, resume: false, cancel: true });
-    expect(logic.runActions("paused")).toEqual({ pause: true, resume: true, cancel: true });
-    expect(logic.runActions("completed")).toEqual({ pause: false, resume: false, cancel: false });
-    expect(logic.runActions("cancelled")).toEqual({ pause: false, resume: false, cancel: false });
-    expect(logic.runActions("failed")).toEqual({ pause: false, resume: false, cancel: false });
-    expect(logic.runActions("queued")).toEqual({ pause: true, resume: false, cancel: true });
-  });
-
-  it("calls the action the button names", () => {
-    const seen: logic.RunAction[] = [];
-    const node = view.renderRunHeader({
-      run: sampleRunDetail({ status: "paused" }),
-      errors: new Map<string, string>(),
-      onAction: (action) => {
-        seen.push(action);
-      },
-    });
-    node.querySelector<HTMLButtonElement>(".run-action-resume")?.click();
-    node.querySelector<HTMLButtonElement>(".run-action-pause")?.click();
-    expect(seen).toEqual(["resume", "pause"]);
-  });
-});
-
-describe("the pause reason in words a person understands", () => {
-  it("maps login_required and challenge to an actionable sentence", () => {
-    expect(logic.humanizePauseReason("login_required")).toBe(
-      "Log in to the site in the bound tab, then resume.",
-    );
-    const challenge = logic.humanizePauseReason("challenge");
-    expect(challenge).not.toBeNull();
-    expect(challenge).toContain("bound tab");
-    expect(challenge).toContain("resume");
-  });
-
-  it("humanizes a reason it has never heard of", () => {
-    const text = logic.humanizePauseReason("network_error");
-    expect(text).toContain("Network error");
-    expect(text).toContain("resume");
-  });
-
-  it("renders the reason, the status and the counts", () => {
-    const node = header("paused", "login_required");
-    expect(node.querySelector(".pause-reason")?.textContent).toBe(
-      "Log in to the site in the bound tab, then resume.",
-    );
-    expect(node.querySelector(".run-status")?.textContent).toBe("Paused");
-    expect(node.querySelector(".count-parked .count-value")?.textContent).toBe("1");
-    expect(node.querySelector(".count-total .count-label")?.textContent).toBe("Total: ");
-  });
-
-  it("shows a plain sentence when there is no reason", () => {
-    expect(header("running").querySelector(".pause-reason")?.textContent).toBe("Not paused.");
-  });
-});
-
-describe("the results link", () => {
-  it("points at the run's results.csv on this origin", () => {
-    const link = header("completed").querySelector<HTMLAnchorElement>(".results-link");
-    expect(link?.getAttribute("href")).toBe("/api/v1/runs/run-1/results.csv");
-  });
-});
diff --git a/apps/web/tests/shell.test.tsx b/apps/web/tests/shell.test.tsx
new file mode 100644
index 0000000..7cc6bc9
--- /dev/null
+++ b/apps/web/tests/shell.test.tsx
@@ -0,0 +1,122 @@
+/** The shell: the sidebar of DESIGN.md §6, the header, the count, and the extension status. */
+
+import { cleanup, fireEvent, screen, within } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { createFetchStub, renderApp, settle, type FetchStub } from "./helpers";
+
+const TASK = {
+  workflow_id: "w-1",
+  recipe_version_id: "r-1",
+  name: "Add inquiries",
+  app: "crm.example.com",
+  last_run: null,
+};
+
+function stubWith(needsHelp: unknown[], attached: boolean): FetchStub {
+  return createFetchStub({
+    "/api/v1/needs-help": { body: needsHelp },
+    "/api/v1/executor/session": { body: { attached } },
+    "/api/v1/tasks": { body: [TASK] },
+  });
+}
+
+let stub: FetchStub;
+
+beforeEach(() => {
+  stub = stubWith([], false);
+});
+
+afterEach(() => {
+  stub.restore();
+  cleanup();
+});
+
+describe("the sidebar", () => {
+  it("shows every place the design names, in its groups", () => {
+    renderApp("/");
+
+    for (const label of [
+      "Home",
+      "Needs help",
+      "Tasks",
+      "Runs",
+      "Spreadsheets",
+      "Documents",
+      "Saved answers",
+      "Apps",
+      "Settings",
+      "Help",
+    ]) {
+      expect(screen.getByRole("link", { name: label }), label).toBeTruthy();
+    }
+    for (const group of ["Automate", "Your data", "Connect"]) {
+      expect(screen.getByText(group)).toBeTruthy();
+    }
+  });
+
+  it("routes each item to a real page, not to a placeholder href", () => {
+    renderApp("/");
+
+    expect(screen.getByRole("link", { name: "Runs" }).getAttribute("href")).toBe("/runs");
+    expect(screen.getByRole("link", { name: "Saved answers" }).getAttribute("href")).toBe(
+      "/saved-answers",
+    );
+  });
+
+  it("says Chrome not connected when no session is attached", async () => {
+    renderApp("/");
+
+    expect(await screen.findByText("Chrome not connected")).toBeTruthy();
+    expect(screen.queryByText("Chrome connected")).toBeNull();
+  });
+
+  it("says Chrome connected when the API reports an attached session", async () => {
+    stub.restore();
+    stub = stubWith([], true);
+    renderApp("/");
+
+    expect(await screen.findByText("Chrome connected")).toBeTruthy();
+  });
+
+  it("shows the count of rows that need help only when there is something to count", async () => {
+    stub.restore();
+    stub = stubWith([{ record_id: "rec-1", run_id: "run-1", task_name: "Add inquiries", row: "ACME-1", state: "parked", reason: null, commit_attempted: false }], false);
+    stub.calls.length = 0;
+    const first = renderApp("/");
+    const nav = screen.getByRole("link", { name: /Needs help/ });
+    expect(await within(nav).findByText("1")).toBeTruthy();
+    first.unmount();
+
+    stub.restore();
+    stub = stubWith([], false);
+    renderApp("/");
+    await settle();
+    expect(within(screen.getByRole("link", { name: "Needs help" })).queryByText("1")).toBeNull();
+  });
+});
+
+describe("the header", () => {
+  it("shows the page title, one primary action and the avatar", () => {
+    renderApp("/");
+
+    expect(screen.getByRole("heading", { level: 2 }).textContent).toBe("Home");
+    expect(screen.getByRole("link", { name: "Teach a new task" }).getAttribute("href")).toBe(
+      "/teach",
+    );
+    expect(document.querySelectorAll(".btn.primary")).toHaveLength(1);
+    expect(screen.getByLabelText("You")).toBeTruthy();
+  });
+
+  it("opens the search over task names with Ctrl K and closes it with Escape", async () => {
+    renderApp("/");
+    expect(screen.queryByRole("dialog", { name: "Search tasks" })).toBeNull();
+
+    fireEvent.keyDown(window, { key: "k", ctrlKey: true });
+    const panel = await screen.findByRole("dialog", { name: "Search tasks" });
+    expect(await within(panel).findByText("Add inquiries")).toBeTruthy();
+
+    fireEvent.keyDown(window, { key: "Escape" });
+    expect(screen.queryByRole("dialog", { name: "Search tasks" })).toBeNull();
+  });
+});
diff --git a/apps/web/tests/words.test.ts b/apps/web/tests/words.test.ts
new file mode 100644
index 0000000..a90ec38
--- /dev/null
+++ b/apps/web/tests/words.test.ts
@@ -0,0 +1,184 @@
+/** The plain-words vocabulary: the mapping table, the reasons, and the two word forms. */
+
+import { describe, expect, it } from "vitest";
+
+import {
+  durationWords,
+  isOpenStatus,
+  minutesSavedWords,
+  pauseReasonWords,
+  plainReason,
+  relativeTime,
+  rowOutcome,
+  runActions,
+  runStatusWords,
+} from "../src/lib/words";
+
+describe("rowOutcome", () => {
+  it("maps every state of the ledger to the design's words", () => {
+    const expected: Array<[string, string, string]> = [
+      ["pending", "Waiting", "idle"],
+      ["claimed", "Waiting", "idle"],
+      ["prechecked", "Waiting", "idle"],
+      ["filling", "Waiting", "idle"],
+      ["submitting", "Checking…", "live"],
+      ["submitted_unverified", "Checking…", "live"],
+      ["reconciling", "Checking…", "live"],
+      ["verified", "Done", "ok"],
+      ["skipped", "Already there", "idle"],
+      ["parked", "Needs your help", "help"],
+      ["failed", "Didn't work", "help"],
+    ];
+
+    for (const [state, label, tone] of expected) {
+      expect(rowOutcome(state), state).toEqual({ label, tone });
+    }
+  });
+
+  it("falls back to Waiting for a state it does not know", () => {
+    expect(rowOutcome("something_new")).toEqual({ label: "Waiting", tone: "idle" });
+  });
+
+  it("never shows the engine's own word on screen", () => {
+    for (const state of ["parked", "verified", "submitting", "submitted_unverified", "reconciling"]) {
+      expect(rowOutcome(state).label.toLowerCase()).not.toContain(state);
+    }
+  });
+});
+
+describe("runStatusWords", () => {
+  it("maps every run status to the design's words", () => {
+    expect(runStatusWords("queued")).toEqual({ label: "Queued", tone: "idle" });
+    expect(runStatusWords("running")).toEqual({ label: "Running", tone: "live" });
+    expect(runStatusWords("paused")).toEqual({ label: "Paused", tone: "help" });
+    expect(runStatusWords("completed")).toEqual({ label: "Finished", tone: "ok" });
+    expect(runStatusWords("cancelled")).toEqual({ label: "Stopped", tone: "idle" });
+    expect(runStatusWords("failed")).toEqual({ label: "Didn't work", tone: "help" });
+  });
+});
+
+describe("plainReason", () => {
+  it("turns each reason the runner writes into one sentence", () => {
+    expect(plainReason("attempts exhausted")).toBe("It didn't work after three tries.");
+    expect(plainReason("already committed in an earlier run")).toBe(
+      "It was already added in an earlier run.",
+    );
+    expect(plainReason("run cancelled")).toBe("The run was stopped before this row was reached.");
+    expect(plainReason("dismissed by a person")).toBe("You dismissed this row.");
+    expect(plainReason("duplicate")).toBe("It was already there.");
+  });
+
+  it("shows a reason the runner wrote for a person as it stands, and never a missing one", () => {
+    expect(plainReason("The salesperson isn't in Odoo.")).toBe("The salesperson isn't in Odoo.");
+    expect(plainReason("A value it needs is missing from the row.")).toBe(
+      "A value it needs is missing from the row.",
+    );
+    expect(plainReason(null)).toBe("Something went wrong.");
+    expect(plainReason("   ")).toBe("Something went wrong.");
+  });
+
+  it("never lets an identifier reach the screen, even for a code it has never seen", () => {
+    expect(plainReason("some_new_code")).toBe("Some new code.");
+  });
+});
+
+describe("pauseReasonWords", () => {
+  it("says what a person can do about a pause", () => {
+    expect(pauseReasonWords("paused_by_operator")).toBe(
+      "You paused this run. Resume when you are ready.",
+    );
+    expect(pauseReasonWords("login_required")).toBe(
+      "Log in to the site in the bound tab, then resume.",
+    );
+    expect(pauseReasonWords("challenge")).toBe(
+      "Solve the security challenge the site is showing in the bound tab, then resume.",
+    );
+    expect(pauseReasonWords("awaiting_approval")).toBe(
+      "An approval request is waiting for your decision, then resume.",
+    );
+    expect(pauseReasonWords("rate_limited")).toBe(
+      "The site is rate limiting us. Wait a moment, then resume.",
+    );
+    expect(pauseReasonWords("destination_unreachable")).toBe(
+      "The site could not be reached. Check it, then resume.",
+    );
+  });
+
+  it("accepts the older spelling and the case the API happens to send", () => {
+    expect(pauseReasonWords("operator_paused")).toBe(
+      "You paused this run. Resume when you are ready.",
+    );
+    expect(pauseReasonWords("  Login_Required ")).toBe(
+      "Log in to the site in the bound tab, then resume.",
+    );
+  });
+
+  it("writes a reason it has never seen as a sentence, not an identifier", () => {
+    expect(pauseReasonWords("network_error")).toBe(
+      "Paused: Network error. Sort that out, then resume.",
+    );
+  });
+
+  it("answers null when the run is not paused for a reason", () => {
+    expect(pauseReasonWords(null)).toBeNull();
+    expect(pauseReasonWords("  ")).toBeNull();
+  });
+});
+
+describe("runActions and isOpenStatus", () => {
+  it("offers the right buttons for each status", () => {
+    expect(runActions("running")).toEqual({ pause: true, resume: false, cancel: true });
+    expect(runActions("queued")).toEqual({ pause: true, resume: false, cancel: true });
+    expect(runActions("paused")).toEqual({ pause: true, resume: true, cancel: true });
+    expect(runActions("completed")).toEqual({ pause: false, resume: false, cancel: false });
+    expect(runActions("failed")).toEqual({ pause: false, resume: false, cancel: false });
+  });
+
+  it("counts queued, running and paused as open", () => {
+    expect(isOpenStatus("queued")).toBe(true);
+    expect(isOpenStatus("running")).toBe(true);
+    expect(isOpenStatus("paused")).toBe(true);
+    expect(isOpenStatus("completed")).toBe(false);
+    expect(isOpenStatus("cancelled")).toBe(false);
+    expect(isOpenStatus("failed")).toBe(false);
+    expect(isOpenStatus(null)).toBe(false);
+  });
+});
+
+describe("relativeTime", () => {
+  const now = new Date("2026-10-15T12:00:00Z");
+
+  it("says when something happened, in words", () => {
+    expect(relativeTime("2026-10-15T11:59:30Z", now)).toBe("Now");
+    expect(relativeTime("2026-10-15T11:58:00Z", now)).toBe("2 minutes ago");
+    expect(relativeTime("2026-10-15T11:00:00Z", now)).toBe("1 hour ago");
+    expect(relativeTime("2026-10-15T10:00:00Z", now)).toBe("2 hours ago");
+    expect(relativeTime("2026-10-14T11:00:00Z", now)).toBe("Yesterday");
+    expect(relativeTime("2026-10-12T11:00:00Z", now)).toBe("3 days ago");
+  });
+
+  it("says Never when there is no time at all", () => {
+    expect(relativeTime(null, now)).toBe("Never");
+    expect(relativeTime("", now)).toBe("Never");
+    expect(relativeTime("not a date", now)).toBe("Never");
+  });
+});
+
+describe("durationWords and minutesSavedWords", () => {
+  it("writes minutes as hours and minutes, and never goes negative", () => {
+    expect(durationWords(372)).toBe("6 h 12 m");
+    expect(durationWords(60)).toBe("1 h");
+    expect(durationWords(45)).toBe("45 m");
+    expect(durationWords(0)).toBe("0 m");
+    expect(durationWords(-30)).toBe("0 m");
+  });
+
+  it("says how much time was saved, the way a person would", () => {
+    expect(minutesSavedWords(52)).toBe("About 52 minutes saved");
+    expect(minutesSavedWords(60)).toBe("About 1 hour saved");
+    expect(minutesSavedWords(125)).toBe("About 2 hours saved");
+    expect(minutesSavedWords(1)).toBe("About 1 minute saved");
+    expect(minutesSavedWords(0)).toBe("Nothing saved yet");
+    expect(minutesSavedWords(-5)).toBe("Nothing saved yet");
+  });
+});
diff --git a/apps/web/tsconfig.json b/apps/web/tsconfig.json
index a724f4c..dbaa84d 100644
--- a/apps/web/tsconfig.json
+++ b/apps/web/tsconfig.json
@@ -4,6 +4,7 @@
     "module": "ESNext",
     "moduleResolution": "bundler",
     "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx",
     "types": ["node", "vitest/globals"],
     "strict": true,
     "noUncheckedIndexedAccess": true,
diff --git a/apps/web/vite.config.ts b/apps/web/vite.config.ts
index a8f1c72..73c0b98 100644
--- a/apps/web/vite.config.ts
+++ b/apps/web/vite.config.ts
@@ -1,3 +1,4 @@
+import react from "@vitejs/plugin-react";
 import { defineConfig } from "vitest/config";
 
 /**
@@ -5,16 +6,18 @@ import { defineConfig } from "vitest/config";
  * and `vitest run` uses the same environment the page runs in.
  */
 export default defineConfig({
-  // The API serves the page at `/`, so relative asset URLs keep the page working whatever host and
-  // port the operator binds.
-  base: "./",
+  plugins: [react()],
+  // The API serves the built page from this origin's root, so every asset URL is absolute. A
+  // relative base would resolve the assets of a deep route such as `/runs/abc` under `/runs/` and
+  // 404 on a refresh.
+  base: "/",
   build: {
     outDir: "dist",
     emptyOutDir: true,
   },
   test: {
     environment: "happy-dom",
-    include: ["tests/**/*.test.ts"],
+    include: ["tests/**/*.test.ts", "tests/**/*.test.tsx"],
     globals: true,
   },
 });
diff --git a/services/api/hub.py b/services/api/hub.py
index a38992f..2b688ca 100644
--- a/services/api/hub.py
+++ b/services/api/hub.py
@@ -478,6 +478,23 @@ async def detach_executor_session(
     return {"detached": True}
 
 
+@router.get("/executor/session")
+async def read_executor_session(request: Request) -> dict[str, Any]:
+    """Whether an extension session is attached right now, for the sidebar's status line.
+
+    Read-only, so nothing here touches a socket, a frame, a token check or the protocol version.
+    The answer comes from the hub's own in-memory registry, read under the same lock the rest of the
+    hub uses and after the same expiry purge, so a session whose life has run out is not reported as
+    attached. The status lives nowhere else: no database row knows about a Chrome tab.
+    """
+    if not _request_is_local(request):
+        raise _forbidden("the executor API answers only on the local interface")
+    async with _sessions_lock:
+        _purge_expired(time.time())
+        attached = any(row.extension is not None for row in _sessions.values())
+    return {"attached": attached}
+
+
 @router.websocket("/executor/ws")
 async def executor_socket(websocket: WebSocket, session: str | None = None) -> None:
     """The extension's socket: one per session, and its first frame carries the resume token."""
diff --git a/services/api/main.py b/services/api/main.py
index 3e45a29..03f16c6 100644
--- a/services/api/main.py
+++ b/services/api/main.py
@@ -10,13 +10,17 @@
 import logging
 import os
 import uuid
+from collections.abc import MutableMapping
 from pathlib import Path
+from typing import Any
 
 import psycopg
 from fastapi import FastAPI, HTTPException
 from fastapi.responses import PlainTextResponse
 from fastapi.staticfiles import StaticFiles
 from pydantic import BaseModel
+from starlette.exceptions import HTTPException as StarletteHTTPException
+from starlette.responses import Response
 
 from .approvals import router as approvals_router
 from .compile import router as compile_router
@@ -113,8 +117,31 @@ def operator() -> OperatorResponse:
 # routers, ``/health`` and ``/api/v1/operator`` alike. When the page has not been built there is
 # nothing to mount, and ``/`` answers one line telling the operator how to build it rather than
 # crashing at import or serving a directory that is not there.
+class SpaStaticFiles(StaticFiles):
+    """The built page, with one rule: a client-side route is not a missing file.
+
+    A person can refresh on ``/runs/abc``. No such file exists, so the mount would answer 404 and
+    the page would never load. A path with no file extension therefore answers ``index.html`` and
+    the router inside the page decides what to draw. A missing *asset* -- ``*.js``, ``*.css``,
+    ``*.png`` and the rest -- still 404s, so a broken build is visible rather than a page that
+    quietly serves a stylesheet that is not there.
+    """
+
+    async def get_response(self, path: str, scope: MutableMapping[str, Any]) -> Response:
+        """Answer the file, or the page for a route, or 404 for a missing asset."""
+        try:
+            response = await super().get_response(path, scope)
+        except StarletteHTTPException as exc:
+            if exc.status_code != 404 or Path(path).suffix:
+                raise
+            return await super().get_response("index.html", scope)
+        if response.status_code == 404 and not Path(path).suffix:
+            return await super().get_response("index.html", scope)
+        return response
+
+
 if WEB_DIST.is_dir():
-    app.mount("/", StaticFiles(directory=WEB_DIST, html=True), name="web")
+    app.mount("/", SpaStaticFiles(directory=WEB_DIST, html=True), name="web")
 else:
 
     @app.get("/", response_class=PlainTextResponse, include_in_schema=False)
diff --git a/tests/api/test_hub_session_state.py b/tests/api/test_hub_session_state.py
new file mode 100644
index 0000000..c96152b
--- /dev/null
+++ b/tests/api/test_hub_session_state.py
@@ -0,0 +1,85 @@
+"""The sidebar's extension status: whether a session is attached right now.
+
+The hub is an in-memory relay that never touches the database, so these tests need no
+``DATABASE_URL`` and start from an empty registry. The route only reads the registry under its own
+lock; the sockets are covered by ``tests/runner/test_hub.py``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import cast
+
+import pytest
+from fastapi.testclient import TestClient
+from pytest import MonkeyPatch
+from starlette.websockets import WebSocket
+
+from services.api import hub
+from services.api.hub import Peer, Session, reset_sessions
+
+SESSION_STATE_PATH = "/api/v1/executor/session"
+EXTENSION_CLIENT = {"x-processlens-client": "extension"}
+
+
+@pytest.fixture(autouse=True)
+def _empty_registry() -> Iterator[None]:
+    """Every test starts from nothing, and leaves nothing behind."""
+    reset_sessions()
+    yield
+    reset_sessions()
+
+
+def _session(session_id: str = "session-1", expires_at: float = 1e12) -> Session:
+    """One registry row, built the way the popup's Connect call builds it."""
+    return Session(
+        session_id=session_id,
+        session_token="session-token",
+        resume_token=None,
+        tab_url="https://example.test/leads/new",
+        tab_title="New lead",
+        expires_at=expires_at,
+    )
+
+
+def test_no_session_at_all_means_not_attached(client: TestClient) -> None:
+    """With nothing open, the sidebar says Chrome is not connected."""
+    response = client.get(SESSION_STATE_PATH)
+
+    assert response.status_code == 200, response.text
+    assert response.json() == {"attached": False}
+
+
+def test_an_open_session_that_has_not_dialled_in_is_not_attached(
+    monkeypatch: MonkeyPatch, client: TestClient
+) -> None:
+    """A session the popup opened is not a connected extension: the socket is what connects it."""
+    monkeypatch.setenv("PROCESSLENS_EXTENSION_ID", "abcdefghijklmnopabcdefghijklmnop")
+    created = client.post(
+        "/api/v1/executor/sessions",
+        json={"tab_url": "https://example.test/leads/new", "tab_title": "New lead"},
+        headers=EXTENSION_CLIENT,
+    )
+    assert created.status_code == 201, created.text
+
+    assert client.get(SESSION_STATE_PATH).json() == {"attached": False}
+
+
+def test_a_session_with_the_extension_socket_attached_is_attached(client: TestClient) -> None:
+    """The extension's socket is the one thing that makes the status read connected."""
+    row = _session()
+    row.extension = Peer(role=hub.ROLE_EXTENSION, websocket=cast(WebSocket, None))
+    hub._sessions[row.session_id] = row
+
+    response = client.get(SESSION_STATE_PATH)
+
+    assert response.status_code == 200, response.text
+    assert response.json() == {"attached": True}
+
+
+def test_an_expired_session_is_not_reported_as_attached(client: TestClient) -> None:
+    """The same expiry purge the rest of the hub runs decides it: a dead row is not shown."""
+    row = _session(expires_at=0.0)
+    hub._sessions[row.session_id] = row
+
+    assert client.get(SESSION_STATE_PATH).json() == {"attached": False}
diff --git a/tests/api/test_web_serving.py b/tests/api/test_web_serving.py
new file mode 100644
index 0000000..378d15d
--- /dev/null
+++ b/tests/api/test_web_serving.py
@@ -0,0 +1,39 @@
+"""The built page is served at `/`, and a client-side route is not a missing file.
+
+The tests skip themselves when ``apps/web/dist`` has not been built, exactly as the mount itself
+answers one line instead of crashing when the directory is not there.
+"""
+
+from __future__ import annotations
+
+import pytest
+from fastapi.testclient import TestClient
+
+from services.api.main import WEB_DIST
+
+pytestmark = pytest.mark.skipif(not WEB_DIST.is_dir(), reason="the page has not been built yet")
+
+ROOT_ELEMENT = '<div id="root">'
+
+
+def test_the_built_page_is_served_at_the_root(client: TestClient) -> None:
+    """`/` answers the built page, so the operator can open the app."""
+    response = client.get("/")
+
+    assert response.status_code == 200, response.text
+    assert ROOT_ELEMENT in response.text
+
+
+def test_a_client_side_route_serves_the_page_instead_of_a_404(client: TestClient) -> None:
+    """A refresh on `/runs/abc` loads the app, and the router inside it decides what to draw."""
+    response = client.get("/runs/abc")
+
+    assert response.status_code == 200, response.text
+    assert ROOT_ELEMENT in response.text
+
+
+def test_a_missing_asset_still_404s(client: TestClient) -> None:
+    """A missing `.js` is a missing file, not a route: a broken build must be visible."""
+    response = client.get("/assets/does-not-exist-0000.js")
+
+    assert response.status_code == 404, response.text

From f3662c6ad0b23514ec959ab65329e40709603b64 Mon Sep 17 00:00:00 2001
From: Jayanth Vasupilli <156448548+jayanthvee@users.noreply.github.com>
Date: Thu, 15 Oct 2026 16:14:22 -0700
Subject: [PATCH 03/12] feat(api): add the week's home reads, the needs-help
 set and the saved tasks

One module, three read routes: GET /api/v1/home (the week's counts from the append-only run_record_transitions audit table, the minutes saved as done rows times three minutes minus the window's run time, the top three rows that need a person, the runs still going, and the latest five tasks), GET /api/v1/needs-help, and GET /api/v1/tasks. Every statement lives in packages/ledger/reads.py behind the separation rule, and each route takes the same optional tenant filter /api/v1/recipes takes.

RunDetail and RunClaim now carry the run's started_at and finished_at, which the results screen needs for a finished run's time saved.
---
 internal/docs/sql-patterns.md |  28 ++++
 packages/ledger/__init__.py   |  18 +++
 packages/ledger/models.py     |  51 ++++++++
 packages/ledger/reads.py      | 177 ++++++++++++++++++++++++++
 services/api/home.py          | 203 +++++++++++++++++++++++++++++
 services/api/main.py          |   2 +
 services/api/runs.py          |   6 +
 tests/api/test_home_api.py    | 233 ++++++++++++++++++++++++++++++++++
 8 files changed, 718 insertions(+)
 create mode 100644 services/api/home.py
 create mode 100644 tests/api/test_home_api.py

diff --git a/internal/docs/sql-patterns.md b/internal/docs/sql-patterns.md
index 0b8a89f..4b90b81 100644
--- a/internal/docs/sql-patterns.md
+++ b/internal/docs/sql-patterns.md
@@ -299,6 +299,34 @@ WHERE run_id = $run AND state = 'pending';
 UPDATE runs SET status = 'cancelled' WHERE id = $run;
 ```
 
+## The Home screen's week, help list and task list (read-only)
+
+Three read shapes for PL-023, all in ``packages/ledger/reads.py``. The week's counts come from the
+append-only audit table, not from the run's own timestamps: a row is counted when it *entered*
+``verified`` or ``skipped`` inside the rolling window.
+
+```sql
+-- the week's finished rows (the join to run_records is only the tenant filter)
+SELECT count(*) FILTER (WHERE t.to_state = 'verified') AS done,
+       count(*) FILTER (WHERE t.to_state = 'skipped')  AS already_there
+FROM run_record_transitions t
+JOIN run_records rr ON rr.id = t.run_record_id
+WHERE t.at >= now() - make_interval(days => $1)
+  AND ($2::uuid IS NULL OR rr.tenant_id = $2::uuid);
+
+-- the wall clock the window's runs took (an unclaimed run falls back to its creation time)
+SELECT coalesce(sum(extract(epoch FROM (coalesce(finished_at, now())
+                                          - coalesce(started_at, created_at)))), 0)
+FROM runs
+WHERE coalesce(started_at, created_at) >= now() - make_interval(days => $1)
+  AND ($2::uuid IS NULL OR tenant_id = $2::uuid);
+```
+
+The needs-help set is every record in ``parked`` or ``failed`` across all runs, newest first by the
+audit row that put it in that state; the running set is every run in ``queued``/``running``/
+``paused`` with its per-state counts; and the task list is the latest version of each non-archived
+workflow with its newest run. Their SQL is in the same module, next to these two.
+
 ## Rules
 
 - Never `UPDATE` or `DELETE` on `recipe_versions`, `committed_keys`, `step_events`, `ai_calls`, `approvals`, `run_record_transitions`. Triggers will reject it anyway.
diff --git a/packages/ledger/__init__.py b/packages/ledger/__init__.py
index 64092f7..f6d2894 100644
--- a/packages/ledger/__init__.py
+++ b/packages/ledger/__init__.py
@@ -28,23 +28,32 @@
     ApprovalDecision,
     ApprovalRequestRow,
     JobClaim,
+    NeedsHelpRow,
     RecordClaim,
     RecoveryCounts,
     ResultsRow,
     RunClaim,
     RunListRow,
+    RunningRunRow,
     RunSummaryRow,
+    TaskListRow,
     TransitionRow,
     VerifyResult,
+    WeekCountsRow,
 )
 from .reads import (
+    list_needs_help,
     list_open_approvals,
     list_run_records,
+    list_running_runs,
     list_runs,
+    list_tasks,
     list_transitions,
     results_rows,
     run_of_record,
     run_summary,
+    week_counts,
+    window_run_seconds,
 )
 from .records import (
     change_state,
@@ -89,16 +98,20 @@
     "IllegalTransition",
     "JobClaim",
     "LedgerError",
+    "NeedsHelpRow",
     "RecoveryCounts",
     "RecordClaim",
     "ResultsRow",
     "RunClaim",
     "RunListRow",
     "RunSummaryRow",
+    "RunningRunRow",
     "StaleLease",
     "StateConflict",
+    "TaskListRow",
     "TransitionRow",
     "VerifyResult",
+    "WeekCountsRow",
     "all_records_in_exit_state",
     "begin_commit",
     "change_state",
@@ -115,9 +128,12 @@
     "get_request",
     "get_run",
     "heartbeat",
+    "list_needs_help",
     "list_open_approvals",
     "list_run_records",
+    "list_running_runs",
     "list_runs",
+    "list_tasks",
     "list_transitions",
     "mark_submitted_unverified",
     "open_approval_for_run",
@@ -140,4 +156,6 @@
     "skip_pending_records",
     "take_over_run",
     "verify_commit",
+    "week_counts",
+    "window_run_seconds",
 ]
diff --git a/packages/ledger/models.py b/packages/ledger/models.py
index 9e3b4ef..3b71531 100644
--- a/packages/ledger/models.py
+++ b/packages/ledger/models.py
@@ -36,6 +36,11 @@ class RunClaim:
     worker_id: str | None
     lease_epoch: int
     cancel_requested_at: datetime | None
+    # The two clocks the results screen needs for a finished run's time saved. They arrive with the
+    # rest of the row (``get_run`` reads ``SELECT *``), and they default so a test that builds a run
+    # by hand does not have to invent them.
+    started_at: datetime | None = None
+    finished_at: datetime | None = None
 
 
 @dataclass(frozen=True)
@@ -160,3 +165,49 @@ class ResultsRow:
     attempts: int | None
     destination_ref: str | None
     issues: list[Any] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class WeekCountsRow:
+    """The week's finished rows, counted from the append-only audit table."""
+
+    done: int
+    already_there: int
+
+
+@dataclass(frozen=True)
+class NeedsHelpRow:
+    """One row that needs a person, with the task it came from and its plain reason."""
+
+    record_id: uuid.UUID
+    run_id: uuid.UUID
+    task_name: str
+    row: str
+    state: str
+    reason: str | None
+    commit_attempted: bool
+
+
+@dataclass(frozen=True)
+class RunningRunRow:
+    """One run that is still open, with the progress the page shows."""
+
+    run_id: uuid.UUID
+    task_name: str
+    done: int
+    total: int
+    already_there: int
+
+
+@dataclass(frozen=True)
+class TaskListRow:
+    """One saved task: its latest version, the site it may use, and its newest run."""
+
+    workflow_id: uuid.UUID
+    recipe_version_id: uuid.UUID
+    name: str
+    app: str | None
+    last_run_id: uuid.UUID | None
+    last_run_status: str | None
+    last_run_started_at: datetime | None
+    last_run_counts: dict[str, int]
diff --git a/packages/ledger/reads.py b/packages/ledger/reads.py
index 7d073f3..56dbe03 100644
--- a/packages/ledger/reads.py
+++ b/packages/ledger/reads.py
@@ -13,12 +13,16 @@
 
 from .models import (
     ApprovalRequestRow,
+    NeedsHelpRow,
     RecordClaim,
     ResultsRow,
     RunClaim,
     RunListRow,
+    RunningRunRow,
     RunSummaryRow,
+    TaskListRow,
     TransitionRow,
+    WeekCountsRow,
     _row,
 )
 
@@ -139,14 +143,187 @@ def list_open_approvals(conn: psycopg.Connection, run_id: uuid.UUID) -> list[App
         return [_row(ApprovalRequestRow, row) for row in cur.fetchall()]
 
 
+# The week's finished rows come from ``run_record_transitions``: one row per state change, written
+# by the database trigger, so a row is counted by when it actually reached ``verified`` or
+# ``skipped`` and not by the run's own timestamps. The join to ``run_records`` is only for the
+# tenant filter.
+_WEEK_COUNTS = """
+SELECT
+  count(*) FILTER (WHERE t.to_state = 'verified') AS done,
+  count(*) FILTER (WHERE t.to_state = 'skipped') AS already_there
+FROM run_record_transitions t
+JOIN run_records rr ON rr.id = t.run_record_id
+WHERE t.at >= now() - make_interval(days => %(days)s)
+  AND (%(tenant)s::uuid IS NULL OR rr.tenant_id = %(tenant)s)
+"""
+
+# The wall clock the window's runs took: an unfinished run is counted up to now, and a run that a
+# worker never claimed falls back to its creation time.
+_WINDOW_RUN_SECONDS = """
+SELECT coalesce(
+         sum(extract(epoch FROM (coalesce(finished_at, now()) - coalesce(started_at, created_at)))),
+         0
+       )::double precision AS seconds
+FROM runs
+WHERE coalesce(started_at, created_at) >= now() - make_interval(days => %(days)s)
+  AND (%(tenant)s::uuid IS NULL OR tenant_id = %(tenant)s)
+"""
+
+# Every row across all runs that needs a person, newest first: by when it entered the state it is
+# in now, so a problem that just appeared is at the top. The task's name is the recipe's own, with
+# the workflow name as the fallback, exactly as the runs list does.
+_LIST_NEEDS_HELP = """
+SELECT rr.id AS record_id, rr.run_id,
+       coalesce(rv.recipe -> 'meta' ->> 'name', w.name) AS task_name,
+       rr.record_key AS "row", rr.state::text AS state, rr.reason, rr.commit_attempted,
+       coalesce(entered.at, rr.created_at) AS entered_at
+FROM run_records rr
+JOIN runs ru ON ru.id = rr.run_id
+JOIN recipe_versions rv ON rv.id = ru.recipe_version_id
+JOIN workflows w ON w.id = ru.workflow_id
+LEFT JOIN LATERAL (
+  SELECT max(t.at) AS at
+  FROM run_record_transitions t
+  WHERE t.run_record_id = rr.id AND t.to_state = rr.state
+) entered ON true
+WHERE rr.state IN ('parked', 'failed')
+  AND (%(tenant)s::uuid IS NULL OR rr.tenant_id = %(tenant)s)
+ORDER BY entered_at DESC, rr.id DESC
+"""
+
+# The runs that are still going: ``queued``, ``running`` or ``paused``. ``done`` counts both the
+# rows that were added and the rows that were already there; ``already_there`` isolates the latter.
+_LIST_RUNNING_RUNS = """
+SELECT ru.id AS run_id,
+       coalesce(rv.recipe -> 'meta' ->> 'name', w.name) AS task_name,
+       coalesce(c.verified, 0) + coalesce(c.skipped, 0) AS done,
+       coalesce(c.total, 0) AS total,
+       coalesce(c.skipped, 0) AS already_there
+FROM runs ru
+JOIN recipe_versions rv ON rv.id = ru.recipe_version_id
+JOIN workflows w ON w.id = ru.workflow_id
+LEFT JOIN LATERAL (
+  SELECT count(*) AS total,
+         count(*) FILTER (WHERE rr.state = 'verified') AS verified,
+         count(*) FILTER (WHERE rr.state = 'skipped') AS skipped
+  FROM run_records rr
+  WHERE rr.run_id = ru.id
+) c ON true
+WHERE ru.status IN ('queued', 'running', 'paused')
+  AND (%(tenant)s::uuid IS NULL OR ru.tenant_id = %(tenant)s)
+ORDER BY ru.created_at DESC, ru.id
+"""
+
+# Every saved task: the latest version of each non-archived workflow, newest first. ``app`` is the
+# host of the first site the task may use -- the recipe document's own ``meta.allowed_origins``,
+# with the workflow's configured origins as the fallback for a version that predates that field.
+# ``last_run`` is the newest run of the workflow, or all-NULL when it has never run.
+_LIST_TASKS = """
+SELECT workflow_id, recipe_version_id, name,
+       CASE
+         WHEN origin IS NULL OR origin = '' THEN NULL
+         ELSE split_part(
+           regexp_replace(origin, '^[a-zA-Z][a-zA-Z0-9+.-]*://', ''),
+           '/', 1
+         )
+       END AS app,
+       last_run_id, last_run_status, last_run_started_at, last_run_counts
+FROM (
+  SELECT rv.workflow_id, rv.id AS recipe_version_id,
+         coalesce(rv.recipe -> 'meta' ->> 'name', w.name) AS name,
+         coalesce(rv.recipe -> 'meta' -> 'allowed_origins' ->> 0, w.allowed_origins[1]) AS origin,
+         last.id AS last_run_id, last.status::text AS last_run_status,
+         last.started_at AS last_run_started_at,
+         coalesce(last.counts, '{}'::jsonb) AS last_run_counts,
+         rv.created_at AS created_at
+  FROM recipe_versions rv
+  JOIN workflows w ON w.id = rv.workflow_id
+  LEFT JOIN LATERAL (
+    SELECT ru.id, ru.status, ru.started_at,
+           (SELECT coalesce(jsonb_object_agg(s.state::text, s.n), '{}'::jsonb)
+            FROM (
+              SELECT state, count(*) AS n FROM run_records WHERE run_id = ru.id GROUP BY state
+            ) s) AS counts
+    FROM runs ru
+    WHERE ru.workflow_id = rv.workflow_id AND ru.tenant_id = rv.tenant_id
+    ORDER BY ru.created_at DESC, ru.id
+    LIMIT 1
+  ) last ON true
+  WHERE w.archived_at IS NULL
+    AND rv.version = (
+      SELECT max(v.version) FROM recipe_versions v WHERE v.workflow_id = rv.workflow_id
+    )
+    AND (%(tenant)s::uuid IS NULL OR rv.tenant_id = %(tenant)s)
+) ranked
+ORDER BY created_at DESC, recipe_version_id
+LIMIT %(limit)s
+"""
+
+
+def week_counts(
+    conn: psycopg.Connection, *, days: int, tenant_id: uuid.UUID | None = None
+) -> WeekCountsRow:
+    """How many rows entered ``verified`` and ``skipped`` in the last ``days`` days."""
+    with conn.cursor(row_factory=dict_row) as cur:
+        cur.execute(_WEEK_COUNTS, {"days": days, "tenant": tenant_id})
+        return _row(WeekCountsRow, cur.fetchone())
+
+
+def window_run_seconds(
+    conn: psycopg.Connection, *, days: int, tenant_id: uuid.UUID | None = None
+) -> float:
+    """The wall clock, in seconds, that the runs started in the last ``days`` days took."""
+    with conn.cursor() as cur:
+        cur.execute(_WINDOW_RUN_SECONDS, {"days": days, "tenant": tenant_id})
+        row = cur.fetchone()
+    return float(row[0]) if row is not None else 0.0
+
+
+def list_needs_help(
+    conn: psycopg.Connection, *, tenant_id: uuid.UUID | None = None
+) -> list[NeedsHelpRow]:
+    """Every row in state ``parked`` or ``failed``, newest first."""
+    with conn.cursor(row_factory=dict_row) as cur:
+        cur.execute(_LIST_NEEDS_HELP, {"tenant": tenant_id})
+        return [_row(NeedsHelpRow, row) for row in cur.fetchall()]
+
+
+def list_running_runs(
+    conn: psycopg.Connection, *, tenant_id: uuid.UUID | None = None
+) -> list[RunningRunRow]:
+    """The runs that are queued, running or paused, newest first, with their progress."""
+    with conn.cursor(row_factory=dict_row) as cur:
+        cur.execute(_LIST_RUNNING_RUNS, {"tenant": tenant_id})
+        return [_row(RunningRunRow, row) for row in cur.fetchall()]
+
+
+def list_tasks(
+    conn: psycopg.Connection, *, tenant_id: uuid.UUID | None = None, limit: int | None = None
+) -> list[TaskListRow]:
+    """The latest version of every non-archived workflow, newest first.
+
+    ``limit`` of ``None`` is every task (the SQL ``LIMIT NULL`` is no limit).
+    """
+    with conn.cursor(row_factory=dict_row) as cur:
+        cur.execute(_LIST_TASKS, {"tenant": tenant_id, "limit": limit})
+        return [_row(TaskListRow, row) for row in cur.fetchall()]
+
+
 __all__ = [
     "RunClaim",
     "RunListRow",
+    "TaskListRow",
+    "WeekCountsRow",
+    "list_needs_help",
     "list_open_approvals",
     "list_run_records",
+    "list_running_runs",
     "list_runs",
+    "list_tasks",
     "list_transitions",
     "results_rows",
     "run_of_record",
     "run_summary",
+    "week_counts",
+    "window_run_seconds",
 ]
diff --git a/services/api/home.py b/services/api/home.py
new file mode 100644
index 0000000..558c1d2
--- /dev/null
+++ b/services/api/home.py
@@ -0,0 +1,203 @@
+"""The Home screen's own reads: the week's counts, the time saved, the rows that need a person,
+the runs that are still going, and the saved tasks.
+
+Every query lives in ``packages.ledger.reads`` (the separation rule,
+``tests/runner/test_sql_separation.py``); this module only calls those functions and shapes the
+JSON, so it writes no ledger statement of its own.
+
+The week's counts and the minutes saved come from the append-only audit table
+``run_record_transitions`` -- one row per state change, written by the database trigger, not by
+this API. A row is "done" when it entered ``verified`` inside the rolling last seven days and
+"already there" when it entered ``skipped``; neither is inferred from a run's own status.
+
+Minutes saved is three minutes for every done row, minus the wall clock the window's runs took,
+clamped at zero and reported in whole minutes.
+
+Three routes are frozen by PL-023: the whole week, the rows that need a person, and the saved
+tasks. All three take the optional ``tenant_id`` filter ``/api/v1/recipes`` takes, so a test can
+scope itself in a shared session database.
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+from typing import Annotated
+
+from fastapi import APIRouter, Query
+from pydantic import BaseModel
+
+from packages.ledger import (
+    NeedsHelpRow,
+    TaskListRow,
+    list_needs_help,
+    list_running_runs,
+    list_tasks,
+    week_counts,
+    window_run_seconds,
+)
+
+from .db import connection
+
+router = APIRouter(prefix="/api/v1", tags=["home"])
+
+# The week is the rolling last seven days.
+HOME_WINDOW_DAYS = 7
+# What one row costs a person by hand.
+MINUTES_PER_ROW = 3
+# The Home panels are a glance, not an export: three rows that need a person, five tasks.
+NEEDS_HELP_ON_HOME = 3
+TASKS_ON_HOME = 5
+
+
+class HomeCounts(BaseModel):
+    """The week's counts, in the words the page uses."""
+
+    done: int
+    already_there: int
+    needs_help: int
+
+
+class NeedsHelpEntry(BaseModel):
+    """One row that needs a person."""
+
+    record_id: uuid.UUID
+    run_id: uuid.UUID
+    task_name: str
+    row: str
+    state: str
+    reason: str | None
+    commit_attempted: bool
+
+
+class RunningEntry(BaseModel):
+    """One run that is still going, with its progress."""
+
+    run_id: uuid.UUID
+    task_name: str
+    done: int
+    total: int
+    already_there: int
+
+
+class TaskLastRun(BaseModel):
+    """A task's newest run, or nothing at all when it has never run."""
+
+    run_id: uuid.UUID
+    status: str
+    started_at: datetime | None
+    counts: dict[str, int]
+
+
+class TaskEntry(BaseModel):
+    """One saved task: its name, the site it may use, and its newest run."""
+
+    workflow_id: uuid.UUID
+    recipe_version_id: uuid.UUID
+    name: str
+    app: str | None
+    last_run: TaskLastRun | None
+
+
+class HomeSummary(BaseModel):
+    """`GET /api/v1/home`: the whole week at a glance."""
+
+    window_days: int
+    counts: HomeCounts
+    minutes_saved: int
+    needs_help: list[NeedsHelpEntry]
+    running: list[RunningEntry]
+    tasks: list[TaskEntry]
+
+
+def _needs_help(rows: list[NeedsHelpRow]) -> list[NeedsHelpEntry]:
+    return [
+        NeedsHelpEntry(
+            record_id=row.record_id,
+            run_id=row.run_id,
+            task_name=row.task_name,
+            row=row.row,
+            state=row.state,
+            reason=row.reason,
+            commit_attempted=row.commit_attempted,
+        )
+        for row in rows
+    ]
+
+
+def _tasks(rows: list[TaskListRow]) -> list[TaskEntry]:
+    entries: list[TaskEntry] = []
+    for row in rows:
+        last_run: TaskLastRun | None = None
+        if row.last_run_id is not None:
+            last_run = TaskLastRun(
+                run_id=row.last_run_id,
+                status=row.last_run_status or "queued",
+                started_at=row.last_run_started_at,
+                counts=row.last_run_counts,
+            )
+        entries.append(
+            TaskEntry(
+                workflow_id=row.workflow_id,
+                recipe_version_id=row.recipe_version_id,
+                name=row.name,
+                app=row.app,
+                last_run=last_run,
+            )
+        )
+    return entries
+
+
+@router.get("/home", response_model=HomeSummary)
+def home_summary(tenant_id: Annotated[uuid.UUID | None, Query()] = None) -> HomeSummary:
+    """The week at a glance: the counts, the time saved, help needed, live runs and tasks."""
+    with connection() as conn:
+        counts = week_counts(conn, days=HOME_WINDOW_DAYS, tenant_id=tenant_id)
+        seconds = window_run_seconds(conn, days=HOME_WINDOW_DAYS, tenant_id=tenant_id)
+        needing = list_needs_help(conn, tenant_id=tenant_id)
+        running = list_running_runs(conn, tenant_id=tenant_id)
+        tasks = list_tasks(conn, tenant_id=tenant_id, limit=TASKS_ON_HOME)
+
+    minutes_saved = max(0, round(counts.done * MINUTES_PER_ROW - seconds / 60))
+    return HomeSummary(
+        window_days=HOME_WINDOW_DAYS,
+        counts=HomeCounts(
+            done=counts.done,
+            already_there=counts.already_there,
+            # The count is the whole set, not the three the panel shows: the sidebar and the
+            # needs-help page read the same set.
+            needs_help=len(needing),
+        ),
+        minutes_saved=minutes_saved,
+        needs_help=_needs_help(needing[:NEEDS_HELP_ON_HOME]),
+        running=[
+            RunningEntry(
+                run_id=row.run_id,
+                task_name=row.task_name,
+                done=row.done,
+                total=row.total,
+                already_there=row.already_there,
+            )
+            for row in running
+        ],
+        tasks=_tasks(tasks),
+    )
+
+
+@router.get("/needs-help", response_model=list[NeedsHelpEntry])
+def needs_help(tenant_id: Annotated[uuid.UUID | None, Query()] = None) -> list[NeedsHelpEntry]:
+    """Every row across all runs that needs a person, newest first."""
+    with connection() as conn:
+        rows = list_needs_help(conn, tenant_id=tenant_id)
+    return _needs_help(rows)
+
+
+@router.get("/tasks", response_model=list[TaskEntry])
+def tasks(tenant_id: Annotated[uuid.UUID | None, Query()] = None) -> list[TaskEntry]:
+    """Every saved task, newest first, with the site it may use and its newest run."""
+    with connection() as conn:
+        rows = list_tasks(conn, tenant_id=tenant_id, limit=None)
+    return _tasks(rows)
+
+
+__all__ = ["router"]
diff --git a/services/api/main.py b/services/api/main.py
index 03f16c6..814baf6 100644
--- a/services/api/main.py
+++ b/services/api/main.py
@@ -24,6 +24,7 @@
 
 from .approvals import router as approvals_router
 from .compile import router as compile_router
+from .home import router as home_router
 from .hub import router as hub_router
 from .middleware import FrontDoorMiddleware
 from .recipes import router as recipes_router
@@ -48,6 +49,7 @@
 app.include_router(runs_router)
 app.include_router(approvals_router)
 app.include_router(hub_router)
+app.include_router(home_router)
 
 
 # NOTE: the page's static mount is added at the very END of this module, after every route is
diff --git a/services/api/runs.py b/services/api/runs.py
index 9a94364..38d5a99 100644
--- a/services/api/runs.py
+++ b/services/api/runs.py
@@ -100,6 +100,10 @@ class RunDetail(BaseModel):
     status: str
     pause_reason: str | None
     cancel_requested_at: datetime | None
+    # The wall clock, for the results screen's "about N minutes saved". ``started_at`` is null until
+    # a worker claims the run; ``finished_at`` is null until it ends.
+    started_at: datetime | None = None
+    finished_at: datetime | None = None
     counts: RunCounts
     open_approval: OpenApproval | None = None
 
@@ -225,6 +229,8 @@ def get_run_endpoint(run_id: uuid.UUID) -> RunDetail:
         status=run.status,
         pause_reason=run.pause_reason,
         cancel_requested_at=run.cancel_requested_at,
+        started_at=run.started_at,
+        finished_at=run.finished_at,
         counts=counts,
         open_approval=(
             OpenApproval(
diff --git a/tests/api/test_home_api.py b/tests/api/test_home_api.py
new file mode 100644
index 0000000..519afb1
--- /dev/null
+++ b/tests/api/test_home_api.py
@@ -0,0 +1,233 @@
+"""The Home, needs-help and tasks reads.
+
+The style is ``tests/api/test_runs_reads.py``'s: the ``ledger`` fixture builds a fresh tenant, so
+every assertion here is scoped to this test's own data in the shared session database (each route
+takes the ``tenant_id`` filter for exactly that reason).
+"""
+
+from __future__ import annotations
+
+import json
+import uuid
+
+import psycopg
+from fastapi.testclient import TestClient
+
+from tests.db.seed import Ledger
+
+
+def home_body(connected: TestClient, ledger: Ledger) -> dict:
+    """`GET /api/v1/home`, scoped to this test's tenant."""
+    response = connected.get(f"/api/v1/home?tenant_id={ledger.tenant_id}")
+    assert response.status_code == 200, response.text
+    return response.json()
+
+
+def add_task(
+    conn: psycopg.Connection, ledger: Ledger, *, name: str, origin: str
+) -> tuple[uuid.UUID, uuid.UUID]:
+    """A saved task: one non-archived workflow and its one recipe version, with a real document."""
+    with conn.cursor() as cur:
+        cur.execute(
+            "INSERT INTO workflows (tenant_id, name, destination_key, allowed_origins) "
+            "VALUES (%s, %s, 'demo-crm', %s) RETURNING id",
+            (ledger.tenant_id, name, [origin]),
+        )
+        workflow_id = cur.fetchone()[0]
+        document = {"meta": {"name": name, "allowed_origins": [origin]}, "steps": []}
+        cur.execute(
+            "INSERT INTO recipe_versions (tenant_id, workflow_id, version, recipe, change_reason) "
+            "VALUES (%s, %s, 1, %s, 'compiled from recording') RETURNING id",
+            (ledger.tenant_id, workflow_id, json.dumps(document)),
+        )
+        return workflow_id, cur.fetchone()[0]
+
+
+def test_home_answers_the_frozen_shape(
+    connected: TestClient, conn: psycopg.Connection, ledger: Ledger
+) -> None:
+    """The counts, the minutes, the top needs-help rows, the live run and the tasks, all shaped."""
+    ledger.seed_records(4, state="verified")
+    ledger.seed_records(1, state="skipped")
+    ledger.seed_records(2, state="parked")
+    running, _ = ledger.seed_records(3, state="pending")
+    conn.execute("UPDATE runs SET status = 'running' WHERE id = %s", (running.id,))
+
+    body = home_body(connected, ledger)
+
+    assert set(body) == {
+        "window_days",
+        "counts",
+        "minutes_saved",
+        "needs_help",
+        "running",
+        "tasks",
+    }
+    assert body["window_days"] == 7
+    assert body["counts"] == {"done": 4, "already_there": 1, "needs_help": 2}
+    # Four rows at three minutes each, minus a run that has taken no measurable wall clock.
+    assert body["minutes_saved"] == 12
+
+    assert set(body["counts"]) == {"done", "already_there", "needs_help"}
+    record = body["needs_help"][0]
+    assert set(record) == {
+        "record_id",
+        "run_id",
+        "task_name",
+        "row",
+        "state",
+        "reason",
+        "commit_attempted",
+    }
+    assert record["state"] == "parked"
+    assert record["task_name"] == "Inquiries"
+    assert record["row"]
+    assert record["commit_attempted"] is False
+    assert record["reason"] is None
+
+    live = body["running"][0]
+    assert set(live) == {"run_id", "task_name", "done", "total", "already_there"}
+    assert live["run_id"] == str(running.id)
+    assert live["task_name"] == "Inquiries"
+    assert (live["done"], live["total"], live["already_there"]) == (0, 3, 0)
+
+    task = body["tasks"][0]
+    assert set(task) == {"workflow_id", "recipe_version_id", "name", "app", "last_run"}
+    assert task["workflow_id"] == str(ledger.workflow_id)
+    assert task["name"] == "Inquiries"
+
+
+def test_a_row_that_finished_before_the_window_is_not_counted(
+    connected: TestClient, conn: psycopg.Connection, ledger: Ledger
+) -> None:
+    """The counts read the audit table's own timestamps, so an older finish is not this week's."""
+    ledger.seed_records(1, state="verified")
+    _, old_ids = ledger.seed_records(1, state="pending")
+    # The audit trigger stamps ``now()`` on every row it writes, so a row that finished before the
+    # window is placed by writing its audit row with an older ``at``. The read counts audit rows,
+    # so this is the only honest way to test the window filter.
+    conn.execute(
+        "INSERT INTO run_record_transitions "
+        "(tenant_id, run_record_id, from_state, to_state, reason, actor, at) "
+        "VALUES (%s, %s, 'filling', 'verified', 'ran last month', 'worker', "
+        "now() - interval '30 days')",
+        (ledger.tenant_id, old_ids[0]),
+    )
+
+    body = home_body(connected, ledger)
+
+    assert body["counts"]["done"] == 1
+
+
+def test_the_minutes_saved_are_clamped_at_zero(
+    connected: TestClient, conn: psycopg.Connection, ledger: Ledger
+) -> None:
+    """A run that took longer than the rows were worth saves nothing, never a negative number."""
+    run = ledger.new_run()
+    conn.execute(
+        "UPDATE runs SET created_at = now() - interval '2 hours', "
+        "started_at = now() - interval '2 hours', finished_at = now() WHERE id = %s",
+        (run.id,),
+    )
+
+    body = home_body(connected, ledger)
+
+    assert body["counts"]["done"] == 0
+    assert body["minutes_saved"] == 0
+
+
+def test_the_needs_help_panel_is_the_newest_three_in_order(
+    connected: TestClient, ledger: Ledger
+) -> None:
+    """Newest first, capped at three, while the count is the whole set."""
+    keys: list[str] = []
+    for index in range(4):
+        key = f"row-{index}"
+        run = ledger.new_run()
+        ledger.add_record(run, record_key=key, state="parked")
+        keys.append(key)
+
+    body = home_body(connected, ledger)
+
+    assert [row["row"] for row in body["needs_help"]] == [keys[3], keys[2], keys[1]]
+    assert body["counts"]["needs_help"] == 4
+
+
+def test_the_count_is_the_length_of_the_needs_help_route(
+    connected: TestClient, ledger: Ledger
+) -> None:
+    """The sidebar count and the page come from the same set, so they can never disagree."""
+    ledger.seed_records(2, state="parked")
+    ledger.seed_records(1, state="failed")
+
+    body = home_body(connected, ledger)
+    response = connected.get(f"/api/v1/needs-help?tenant_id={ledger.tenant_id}")
+
+    assert response.status_code == 200, response.text
+    rows = response.json()
+    assert len(rows) == 3
+    assert body["counts"]["needs_help"] == len(rows)
+    assert [row["row"] for row in rows] == [row["row"] for row in body["needs_help"]]
+    assert {row["state"] for row in rows} == {"parked", "failed"}
+
+
+def test_the_tasks_are_capped_with_the_app_from_the_first_allowed_origin(
+    connected: TestClient, conn: psycopg.Connection, ledger: Ledger
+) -> None:
+    """Five tasks on Home, each named as its recipe is and pointing at the host it may use."""
+    for index in range(6):
+        add_task(conn, ledger, name=f"Add inquiries {index}", origin="https://crm.example.com/add")
+
+    body = home_body(connected, ledger)
+
+    assert len(body["tasks"]) == 5
+    assert {task["app"] for task in body["tasks"]} == {"crm.example.com"}
+    assert all(task["name"].startswith("Add inquiries ") for task in body["tasks"])
+
+
+def test_a_task_that_has_never_run_has_no_last_run(
+    connected: TestClient, conn: psycopg.Connection, ledger: Ledger
+) -> None:
+    """A task with no runs yet says so, and a task that has run carries its newest run."""
+    workflow_id, recipe_version_id = add_task(
+        conn, ledger, name="Add leads", origin="https://twenty.example.com"
+    )
+    never, never_recipe = add_task(
+        conn, ledger, name="Update prices", origin="https://inventory.example.com"
+    )
+    conn.execute(
+        "INSERT INTO runs "
+        "(tenant_id, workflow_id, recipe_version_id, input_batch_id, mode, status, "
+        "destination_key) "
+        "VALUES (%s, %s, %s, NULL, 'batch', 'completed', 'demo-crm')",
+        (ledger.tenant_id, workflow_id, recipe_version_id),
+    )
+
+    response = connected.get(f"/api/v1/tasks?tenant_id={ledger.tenant_id}")
+
+    assert response.status_code == 200, response.text
+    tasks = {task["workflow_id"]: task for task in response.json()}
+    assert tasks[str(never)]["name"] == "Update prices"
+    assert tasks[str(never)]["recipe_version_id"] == str(never_recipe)
+    assert tasks[str(never)]["last_run"] is None
+    ran = tasks[str(workflow_id)]["last_run"]
+    assert ran is not None
+    assert ran["status"] == "completed"
+    assert ran["started_at"] is None
+    assert ran["counts"] == {}
+
+
+def test_the_needs_help_route_is_newest_first_with_the_task_name(
+    connected: TestClient, ledger: Ledger
+) -> None:
+    """Each row carries the row it came from, the task it belongs to and its plain reason."""
+    run = ledger.new_run()
+    first = ledger.add_record(run, record_key="ACME-1", state="parked")
+    second = ledger.add_record(run, record_key="ACME-2", state="failed")
+
+    rows = connected.get(f"/api/v1/needs-help?tenant_id={ledger.tenant_id}").json()
+
+    assert {row["record_id"] for row in rows} == {str(first), str(second)}
+    assert all(row["task_name"] == "Inquiries" for row in rows)
+    assert all(row["run_id"] == str(run.id) for row in rows)
+    assert [row["row"] for row in rows] == ["ACME-2", "ACME-1"]

From 492335343354d2fae819157279c9a5e414d70c9a Mon Sep 17 00:00:00 2001
From: Jayanth Vasupilli <156448548+jayanthvee@users.noreply.github.com>
Date: Thu, 15 Oct 2026 16:14:26 -0700
Subject: [PATCH 04/12] feat(web): build the Home screen from the week's real
 data

The headline counts real rows, the gold panel shows the minutes saved, Needs your help carries the top three in one plain sentence each, Running now polls every two seconds only while a run is going and stops the moment none is, and My tasks lists the latest five with one quiet action each. Nothing has run yet gets the Teach button instead of an empty figure.
---
 apps/web/src/pages/Home.tsx  | 214 ++++++++++++++++++++++++++++++++++-
 apps/web/src/pages/home.css  |  35 ++++++
 apps/web/tests/home.test.tsx | 169 +++++++++++++++++++++++++++
 3 files changed, 415 insertions(+), 3 deletions(-)
 create mode 100644 apps/web/src/pages/home.css
 create mode 100644 apps/web/tests/home.test.tsx

diff --git a/apps/web/src/pages/Home.tsx b/apps/web/src/pages/Home.tsx
index 80f156e..67e4a68 100644
--- a/apps/web/src/pages/Home.tsx
+++ b/apps/web/src/pages/Home.tsx
@@ -1,6 +1,214 @@
-import { EmptyState } from "../shell/EmptyState";
+import { type CSSProperties, useEffect, useState } from "react";
+import { Link } from "react-router-dom";
 
-/** Placeholder: builder B replaces this file with the Home page of the approved mock. */
+import { useJson } from "../lib/useJson";
+import { durationWords, isOpenStatus, relativeTime, runStatusWords } from "../lib/words";
+import type { HomeSummary, TaskRow } from "../types";
+import "./home.css";
+
+/** The blur-in stagger: the hero and the panels rise in 70 ms apart (DESIGN.md §7). */
+function slot(index: number): CSSProperties {
+  return { "--i": index } as CSSProperties;
+}
+
+/**
+ * The one quiet button a task row offers. The run flow itself arrives in a later ticket, so both
+ * "Run again" and "Try one row" open the task page rather than starting a run.
+ */
+function taskAction(task: TaskRow): { label: string; to: string } {
+  if (task.last_run !== null && task.last_run.status === "running") {
+    return { label: "Open", to: `/runs/${task.last_run.run_id}` };
+  }
+  return task.last_run === null
+    ? { label: "Try one row", to: `/tasks/${task.workflow_id}` }
+    : { label: "Run again", to: `/tasks/${task.workflow_id}` };
+}
+
+/** A task's result in plain words, or how many of its rows need a person (DESIGN.md §2). */
+function taskResult(task: TaskRow): { label: string; tone: string } {
+  const run = task.last_run;
+  if (run === null) return { label: "Ready", tone: "idle" };
+  const failed = run.counts.failed ?? 0;
+  const parked = run.counts.parked ?? 0;
+  // A run that is still going leads with its own status; a finished one leads with any row that
+  // needs a person.
+  if (isOpenStatus(run.status)) {
+    const outcome = runStatusWords(run.status);
+    return { label: outcome.label, tone: outcome.tone };
+  }
+  if (failed > 0) return { label: "Didn't work", tone: "help" };
+  if (parked > 0) return { label: `${parked} needs help`, tone: "help" };
+  const outcome = runStatusWords(run.status);
+  return { label: outcome.label, tone: outcome.tone };
+}
+
+/**
+ * Home: the week at a glance. The Shell already renders the page's one primary action
+ * ("Teach a new task"), so every button this page draws itself is quiet.
+ */
 export function Home(): JSX.Element {
-  return <EmptyState sentence="Your week at a glance will appear here." />;
+  // A run that is still going keeps the page live. The moment none is, `pollMs` is null and
+  // `useJson` clears the interval, so a finished week makes no more requests.
+  const [live, setLive] = useState(false);
+  const { data, error } = useJson<HomeSummary>("/api/v1/home", live ? 2000 : null);
+
+  useEffect(() => {
+    setLive((data?.running?.length ?? 0) > 0);
+  }, [data]);
+
+  // A body that is not a week's summary -- a refusal, or a Shell test that never asked for one --
+  // shows one sentence instead of throwing.
+  const counts = data?.counts;
+  if (data === null || counts === undefined) {
+    return (
+      <div className="home">
+        <p className="lede">{error ?? "Loading your week…"}</p>
+      </div>
+    );
+  }
+
+  const running = data.running ?? [];
+  const needsHelp = data.needs_help ?? [];
+  const tasks = data.tasks ?? [];
+  const nothing = counts.done === 0 && counts.needs_help === 0;
+
+  return (
+    <div className="home">
+      <section className="hero">
+        <div>
+          <h1 className="big in" style={slot(1)}>
+            {nothing ? (
+              "Nothing has run yet."
+            ) : (
+              <>
+                {counts.done} rows done this week.
+                <br />
+                <span>{counts.needs_help} need you.</span>
+              </>
+            )}
+          </h1>
+          <p className="lede in" style={slot(2)}>
+            {counts.already_there === 0
+              ? "Nothing was entered twice."
+              : `${counts.already_there} rows were already there.`}
+          </p>
+          {nothing ? (
+            <p className="empty-action in" style={slot(2)}>
+              <Link className="btn quiet" to="/teach">
+                Teach a new task
+              </Link>
+            </p>
+          ) : null}
+        </div>
+        <div className="saved-fig in" style={slot(2)}>
+          <b>{durationWords(data.minutes_saved ?? 0)}</b>
+          <span>Time saved this week</span>
+          <small>vs. about 3 minutes a row by hand</small>
+        </div>
+      </section>
+
+      <section className="two">
+        <div className="panel in" style={slot(3)}>
+          <div className="panel-h">
+            <h3>Needs your help</h3>
+            <Link to="/needs-help">See all</Link>
+          </div>
+          {needsHelp.length === 0 ? (
+            <p className="panel-note">Nothing needs you right now.</p>
+          ) : (
+            <ul className="rows">
+              {needsHelp.map((row) => (
+                <li key={row.record_id}>
+                  <div>
+                    <b>{row.row}</b>
+                    <p>{row.task_name}</p>
+                  </div>
+                  <Link className="btn quiet" to="/needs-help">
+                    Open
+                  </Link>
+                </li>
+              ))}
+            </ul>
+          )}
+        </div>
+
+        <div className="panel in" style={slot(4)}>
+          <div className="panel-h">
+            <h3>Running now</h3>
+            {running.length > 0 ? (
+              <span className="live">
+                <i /> Live
+              </span>
+            ) : null}
+          </div>
+          {running.length === 0 ? (
+            <p className="panel-note">Nothing is running right now.</p>
+          ) : (
+            running.map((run) => (
+              <div className="run" key={run.run_id}>
+                <b>{run.task_name}</b>
+                <div className="track" aria-hidden="true">
+                  <i
+                    style={{
+                      width: `${run.total === 0 ? 0 : Math.round((run.done / run.total) * 100)}%`,
+                    }}
+                  />
+                </div>
+                <div className="meta">
+                  <span>
+                    {run.done} of {run.total} done
+                  </span>
+                  <span>{run.already_there} already there</span>
+                </div>
+              </div>
+            ))
+          )}
+        </div>
+      </section>
+
+      <section className="panel in" style={slot(5)}>
+        <div className="panel-h">
+          <h3>My tasks</h3>
+          <Link to="/tasks">See all</Link>
+        </div>
+        {tasks.length === 0 ? (
+          <p className="panel-note">No tasks yet.</p>
+        ) : (
+          <table>
+            <thead>
+              <tr>
+                <th>Task</th>
+                <th>Last run</th>
+                <th>Result</th>
+                <th />
+              </tr>
+            </thead>
+            <tbody>
+              {tasks.map((task) => {
+                const action = taskAction(task);
+                const result = taskResult(task);
+                return (
+                  <tr key={task.workflow_id}>
+                    <td>
+                      <b>{task.name}</b>
+                      <small>{task.app ?? "—"}</small>
+                    </td>
+                    <td>{relativeTime(task.last_run?.started_at ?? null)}</td>
+                    <td>
+                      <span className={`res ${result.tone}`}>{result.label}</span>
+                    </td>
+                    <td className="act">
+                      <Link className="btn quiet" to={action.to}>
+                        {action.label}
+                      </Link>
+                    </td>
+                  </tr>
+                );
+              })}
+            </tbody>
+          </table>
+        )}
+      </section>
+    </div>
+  );
 }
diff --git a/apps/web/src/pages/home.css b/apps/web/src/pages/home.css
new file mode 100644
index 0000000..e59990c
--- /dev/null
+++ b/apps/web/src/pages/home.css
@@ -0,0 +1,35 @@
+/* Home's own placement. Every shared primitive -- the panels, the buttons, the rows, the tables,
+   the gold figure and the blur-in entrance -- is already ported into styles/global.css from the
+   approved mock, so nothing here duplicates it. */
+
+.home {
+  display: grid;
+  gap: 30px;
+  align-content: start;
+}
+
+.home .hero {
+  align-items: flex-end;
+}
+
+.home .saved-fig {
+  min-width: 190px;
+}
+
+.home .panel-note {
+  margin: 0;
+  padding: 12px 20px 20px;
+  color: var(--ink-2);
+  font-size: 14px;
+}
+
+.home .empty-action {
+  margin: 14px 0 0;
+}
+
+@media (max-width: 780px) {
+  .home .saved-fig {
+    min-width: 0;
+    text-align: left;
+  }
+}
diff --git a/apps/web/tests/home.test.tsx b/apps/web/tests/home.test.tsx
new file mode 100644
index 0000000..15c158e
--- /dev/null
+++ b/apps/web/tests/home.test.tsx
@@ -0,0 +1,169 @@
+import { screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { callsTo, createFetchStub, renderApp, settle } from "./helpers";
+
+const NOW = new Date();
+
+const HOME = {
+  window_days: 7,
+  counts: { done: 412, already_there: 3, needs_help: 2 },
+  minutes_saved: 34,
+  needs_help: [
+    {
+      record_id: "rec-1",
+      run_id: "run-1",
+      task_name: "Add inquiries",
+      row: "ACME-1",
+      state: "parked",
+      reason: "missing email",
+      commit_attempted: false,
+    },
+    {
+      record_id: "rec-2",
+      run_id: "run-1",
+      task_name: "Add inquiries",
+      row: "ACME-2",
+      state: "failed",
+      reason: null,
+      commit_attempted: true,
+    },
+  ],
+  running: [
+    { run_id: "run-1", task_name: "Add inquiries", done: 11, total: 20, already_there: 2 },
+  ],
+  tasks: [
+    {
+      workflow_id: "wf-1",
+      recipe_version_id: "rv-1",
+      name: "Add inquiries",
+      app: "crm.example.com",
+      last_run: {
+        run_id: "run-1",
+        status: "running",
+        started_at: NOW.toISOString(),
+        counts: { verified: 11, parked: 1 },
+      },
+    },
+    {
+      workflow_id: "wf-2",
+      recipe_version_id: "rv-2",
+      name: "Update prices",
+      app: "inventory.example.com",
+      last_run: {
+        run_id: "run-2",
+        status: "completed",
+        started_at: new Date(NOW.getTime() - 2 * 3600_000).toISOString(),
+        counts: { verified: 4, skipped: 1 },
+      },
+    },
+    {
+      workflow_id: "wf-3",
+      recipe_version_id: "rv-3",
+      name: "Add leads",
+      app: null,
+      last_run: null,
+    },
+  ],
+};
+
+/** What the Shell asks for on the way to Home: the help count and the extension's status. */
+const SHELL = {
+  "/api/v1/needs-help": { body: HOME.needs_help },
+  "/api/v1/executor/session": { body: { attached: true } },
+};
+
+const EMPTY = {
+  window_days: 7,
+  counts: { done: 0, already_there: 0, needs_help: 0 },
+  minutes_saved: 0,
+  needs_help: [],
+  running: [],
+  tasks: [],
+};
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+describe("Home", () => {
+  it("shows the week's real numbers in plain words", async () => {
+    const stub = createFetchStub({ "/api/v1/home": { body: HOME }, ...SHELL });
+    renderApp("/");
+    await settle();
+
+    const headline = screen.getByRole("heading", { level: 1 });
+    expect(headline.textContent).toContain("412 rows done this week.");
+    expect(headline.textContent).toContain("2 need you.");
+    expect(screen.getByText("3 rows were already there.")).toBeTruthy();
+
+    // The gold figure is the minutes saved, in hours and minutes.
+    expect(screen.getByText("34 m")).toBeTruthy();
+    expect(screen.getByText("Time saved this week")).toBeTruthy();
+
+    // The two panels: the rows that need a person, and the live run's progress.
+    expect(screen.getByText("ACME-1")).toBeTruthy();
+    expect(screen.getByText("11 of 20 done")).toBeTruthy();
+    expect(screen.getByText("2 already there")).toBeTruthy();
+
+    // My tasks: the name, the site it may use, when it last ran and one quiet button per row.
+    expect(screen.getByText("crm.example.com")).toBeTruthy();
+    expect(screen.getByText("Now")).toBeTruthy();
+    expect(screen.getByText("2 hours ago")).toBeTruthy();
+    expect(screen.getByText("Never")).toBeTruthy();
+    expect(screen.getAllByRole("link", { name: "Run again" })).toHaveLength(1);
+    expect(screen.getAllByRole("link", { name: "Try one row" })).toHaveLength(1);
+    // Two on the help panel, one on the task whose run is still going.
+    expect(screen.getAllByRole("link", { name: "Open" })).toHaveLength(3);
+
+    stub.restore();
+  });
+
+  it("says so when nothing has run yet and offers the one quiet way to start", async () => {
+    const stub = createFetchStub({ "/api/v1/home": { body: EMPTY }, ...SHELL });
+    renderApp("/");
+    await settle();
+
+    expect(screen.getByRole("heading", { level: 1 }).textContent).toBe("Nothing has run yet.");
+    expect(screen.getAllByRole("link", { name: "Teach a new task" }).length).toBeGreaterThan(0);
+    expect(screen.getByText("Nothing needs you right now.")).toBeTruthy();
+    expect(screen.getByText("Nothing is running right now.")).toBeTruthy();
+
+    stub.restore();
+  });
+
+  it("stops polling the moment no run is going", async () => {
+    // Only the interval is faked, so `settle()`'s own timeout still runs and the 2 s poll fires
+    // exactly when this test advances the clock.
+    vi.useFakeTimers({ toFake: ["setInterval", "clearInterval"] });
+    let live = true;
+    const stub = createFetchStub({
+      "/api/v1/home": () => ({ body: live ? HOME : { ...HOME, running: [] } }),
+      ...SHELL,
+    });
+    renderApp("/");
+    await settle();
+    const firstCount = callsTo(stub, "/api/v1/home");
+    expect(firstCount).toBeGreaterThanOrEqual(1);
+
+    // While a run is going, every tick asks again.
+    vi.advanceTimersByTime(2000);
+    await settle();
+    const whileLive = callsTo(stub, "/api/v1/home");
+    expect(whileLive).toBeGreaterThan(firstCount);
+    vi.advanceTimersByTime(2000);
+    await settle();
+    expect(callsTo(stub, "/api/v1/home")).toBeGreaterThan(whileLive);
+
+    // The run ends: the next ask says nothing is running, and the page never asks again.
+    live = false;
+    vi.advanceTimersByTime(2000);
+    await settle();
+    const afterStop = callsTo(stub, "/api/v1/home");
+    vi.advanceTimersByTime(8000);
+    await settle();
+    expect(callsTo(stub, "/api/v1/home")).toBe(afterStop);
+
+    stub.restore();
+  });
+});

From cea26b7643866bc1713accfac5d67d76b3248d7b Mon Sep 17 00:00:00 2001
From: Jayanth Vasupilli <156448548+jayanthvee@users.noreply.github.com>
Date: Thu, 15 Oct 2026 16:20:46 -0700
Subject: [PATCH 05/12] feat(web): add the Tasks and Runs screens and the
 plain-words step sentences

Tasks lists every saved task with its site, its last run and its result, each row carrying one quiet action; a task that has never run offers Try one row. The task page is read-only for now: its steps in one sentence each, and its runs.

Runs lists every run with its progress, and a run page shows live progress with a two-second poll that stops the moment the run is no longer open, Pause/Resume/Cancel with the API's own refusal text beside the button that caused it, each row's plain outcome and reason, Export CSV from this origin, the pause reason in words, and the time saved for a finished run.

lib/steps.ts is the one place a step becomes a sentence: it reads the first rung of the target ladder, so a selector, a test id or a step id can never reach the screen, and a value is only shown when it is a constant.
---
 apps/web/src/lib/steps.ts         | 259 ++++++++++++++++++++++++++
 apps/web/src/pages/RunDetail.tsx  | 272 ++++++++++++++++++++++++++-
 apps/web/src/pages/Runs.tsx       | 123 +++++++++++-
 apps/web/src/pages/TaskDetail.tsx | 148 ++++++++++++++-
 apps/web/src/pages/Tasks.tsx      | 123 +++++++++++-
 apps/web/src/pages/runs.css       |  92 +++++++++
 apps/web/src/pages/tasks.css      |  91 +++++++++
 apps/web/tests/runs.test.tsx      | 300 ++++++++++++++++++++++++++++++
 apps/web/tests/steps.test.ts      | 145 +++++++++++++++
 apps/web/tests/tasks.test.tsx     | 129 +++++++++++++
 10 files changed, 1670 insertions(+), 12 deletions(-)
 create mode 100644 apps/web/src/lib/steps.ts
 create mode 100644 apps/web/src/pages/runs.css
 create mode 100644 apps/web/src/pages/tasks.css
 create mode 100644 apps/web/tests/runs.test.tsx
 create mode 100644 apps/web/tests/steps.test.ts
 create mode 100644 apps/web/tests/tasks.test.tsx

diff --git a/apps/web/src/lib/steps.ts b/apps/web/src/lib/steps.ts
new file mode 100644
index 0000000..66af865
--- /dev/null
+++ b/apps/web/src/lib/steps.ts
@@ -0,0 +1,259 @@
+/**
+ * The one place a step becomes one sentence (plan §5, DESIGN.md §2).
+ *
+ * A person never sees a step id, a target selector, a test id, a variable name or a `record key`.
+ * A step's own `name` always wins when it has one; otherwise the sentence is built from the action
+ * and the first rung of its target ladder (the accessible name), which is the only rung that holds
+ * words a person wrote. The CSS rung and the test-id rung are never read at all.
+ *
+ * `stepWords` is a pure function so `steps.test.ts` can call it directly.
+ */
+
+import type { StepWords } from "../types";
+
+/** One rung of a step's target ladder (plan §5: `$defs/targets`). */
+interface TargetRung {
+  by?: unknown;
+  role?: unknown;
+  name?: unknown;
+  text?: unknown;
+}
+
+/**
+ * The parts of a recipe step this module reads. Everything is optional and guarded, because the
+ * document comes from the API and a page must never assume a field is there.
+ */
+export interface RecipeStep {
+  action?: unknown;
+  name?: unknown;
+  url?: unknown;
+  key?: unknown;
+  value?: unknown;
+  targets?: unknown;
+  condition?: unknown;
+  when?: unknown;
+  outcome?: unknown;
+  op?: unknown;
+  compare?: unknown;
+  as?: unknown;
+}
+
+function text(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed === "" ? undefined : trimmed;
+}
+
+/** A template is not for a person's eyes, so a sentence never falls back to one. */
+function isTemplate(value: string): boolean {
+  return value.includes("{{");
+}
+
+/** The step's own name, when the recipe author gave it one. */
+function stepName(step: RecipeStep): string | undefined {
+  return text(step.name);
+}
+
+/**
+ * The first rung of the target ladder, and only the words in it: the accessible name of the role
+ * rung or the label rung. The test id and the CSS selector are ignored on purpose.
+ */
+function accessibleName(step: RecipeStep): string | undefined {
+  if (!Array.isArray(step.targets)) return undefined;
+  const rung = step.targets[0] as TargetRung | undefined;
+  if (rung === undefined || typeof rung !== "object") return undefined;
+  const by = text(rung.by);
+  if (by === "role") return text(rung.name);
+  if (by === "label") return text(rung.text);
+  return undefined;
+}
+
+/** "title_case" -> "title case", so a closed-vocabulary word is still readable. */
+function words(token: string): string {
+  return token.replace(/[_-]+/g, " ").replace(/\s+/g, " ").trim().toLowerCase();
+}
+
+function lowerFirst(value: string): string {
+  if (value === "") return value;
+  return value.charAt(0).toLowerCase() + value.slice(1);
+}
+
+function upperFirst(value: string): string {
+  if (value === "") return value;
+  return value.charAt(0).toUpperCase() + value.slice(1);
+}
+
+/** "Email" -> "the email"; a phrase that already carries its own article is left alone. */
+function definite(noun: string): string {
+  const clean = noun.trim();
+  if (/^(the|a|an)\s/i.test(clean)) return lowerFirst(clean);
+  return `the ${lowerFirst(clean)}`;
+}
+
+function startsWithVerb(value: string, verb: string): boolean {
+  return value.toLowerCase().startsWith(`${verb.toLowerCase()} `);
+}
+
+/** `verb + object`, unless the object already begins with that verb. */
+function phrase(verb: string, object: string): string {
+  const clean = object.trim();
+  if (startsWithVerb(clean, verb)) return upperFirst(clean);
+  return `${verb} ${clean}`;
+}
+
+/** The site a navigate step opens: the URL's host, never the whole URL and never a template. */
+function hostOf(url: string): string | undefined {
+  if (isTemplate(url)) return undefined;
+  try {
+    const parsed = new URL(url);
+    return parsed.host === "" ? undefined : parsed.host;
+  } catch {
+    return undefined;
+  }
+}
+
+/** A condition, in words a person would use. Never a selector, never a template. */
+function conditionWords(condition: unknown): string {
+  if (condition === null || typeof condition !== "object") return "the page is ready";
+  const keys = Object.keys(condition as Record<string, unknown>);
+  if (keys.includes("text_visible")) return "the page shows what we expect";
+  if (keys.includes("text_absent")) return "the old text is gone";
+  if (keys.includes("url_matches")) return "the page has the right address";
+  if (keys.includes("element_present")) return "the page is ready";
+  if (keys.includes("element_absent")) return "the page has moved on";
+  if (keys.includes("value_equals")) return "the field holds the right value";
+  return "the page is ready";
+}
+
+const END_RECORD: Record<string, string> = {
+  verified: "Finish this row",
+  skipped: "Mark this row as already there",
+  parked: "Pause this row and ask for help",
+  failed: "Stop this row",
+};
+
+const COMPARE: Record<string, string> = {
+  equals: "Check the two values match",
+  contains: "Check one value contains the other",
+  amount_within: "Check the two amounts match",
+};
+
+const AGGREGATE: Record<string, string> = {
+  sum: "Add the values up",
+  count: "Count the values",
+  min: "Find the smallest value",
+  max: "Find the largest value",
+  mean: "Work out the average",
+};
+
+/** One step, in one plain sentence. */
+export function stepWords(step: RecipeStep): StepWords {
+  const action = text(step.action) ?? "";
+  const name = stepName(step);
+  const target = accessibleName(step);
+  const object = name ?? target;
+
+  switch (action) {
+    case "navigate": {
+      const url = text(step.url);
+      const host = url === undefined ? undefined : hostOf(url);
+      return { title: phrase("Open", name ?? host ?? "the site") };
+    }
+    case "fill": {
+      const title = phrase("Type", definite(object ?? "field"));
+      const always = constantValue(step.value);
+      return always === undefined ? { title } : { title, detail: `Always “${always}”` };
+    }
+    case "select": {
+      const title = phrase("Choose", definite(object ?? "option"));
+      const always = constantValue(step.value);
+      return always === undefined ? { title } : { title, detail: `Always “${always}”` };
+    }
+    case "click":
+      return { title: phrase("Click", object ?? "the button") };
+    case "press":
+      return { title: phrase("Press", text(step.key) ?? object ?? "the key") };
+    case "upload_file":
+      return { title: phrase("Attach", definite(object ?? "file")) };
+    case "read_value": {
+      if (name !== undefined && startsWithVerb(name, "Read")) return { title: upperFirst(name) };
+      return { title: `${phrase("Read", definite(object ?? "value"))} from the page` };
+    }
+    case "wait_for": {
+      if (name !== undefined) return { title: upperFirst(name) };
+      return { title: `Wait for ${definite(target ?? "page")}` };
+    }
+    case "assert": {
+      if (name !== undefined) return { title: upperFirst(name) };
+      return { title: `Check ${definite(target ?? "result")}` };
+    }
+    case "download":
+      return { title: `Download ${definite(object ?? "file")}` };
+    case "extract":
+      return { title: `Read ${object === undefined ? "the details" : definite(object)} from the document` };
+    case "classify":
+      return { title: `Choose ${object === undefined ? "the best answer" : definite(object)}` };
+    case "transform": {
+      if (name !== undefined) return { title: upperFirst(name) };
+      return { title: `Work out the ${words(text(step.op) ?? "value")}` };
+    }
+    case "match": {
+      if (name !== undefined) return { title: upperFirst(name) };
+      return { title: COMPARE[text(step.compare) ?? ""] ?? "Compare the two values" };
+    }
+    case "aggregate": {
+      if (name !== undefined) return { title: upperFirst(name) };
+      return { title: AGGREGATE[text(step.op) ?? ""] ?? "Combine the values" };
+    }
+    case "branch": {
+      if (name !== undefined) return { title: upperFirst(name) };
+      const condition = step.when ?? step.condition;
+      return { title: `If ${conditionWords(condition)}, do the steps inside` };
+    }
+    case "for_each": {
+      if (name !== undefined) return { title: upperFirst(name) };
+      const item = text(step.as);
+      return { title: `For each ${item === undefined ? "item" : words(item)}, do the steps inside` };
+    }
+    case "approval_gate":
+      return { title: name === undefined ? "Wait for your approval" : upperFirst(name) };
+    case "end_record":
+      return {
+        title:
+          name === undefined
+            ? (END_RECORD[text(step.outcome) ?? ""] ?? "Finish this row")
+            : upperFirst(name),
+      };
+    default:
+      return { title: name === undefined ? "Do the next thing" : upperFirst(name) };
+  }
+}
+
+/** A plain constant a step always types; a template or an object is not shown to a person. */
+function constantValue(value: unknown): string | undefined {
+  if (value === null || typeof value !== "object") return undefined;
+  const source = value as { kind?: unknown; value?: unknown };
+  if (text(source.kind) !== "constant") return undefined;
+  const constant = text(source.value);
+  return constant === undefined || isTemplate(constant) ? undefined : constant;
+}
+
+/**
+ * Every step of a recipe document, in order. A nested branch or loop is its own sentence and its
+ * inner steps follow it, so a person reads the same order the runner follows.
+ */
+export function stepWordsList(steps: unknown): StepWords[] {
+  if (!Array.isArray(steps)) return [];
+  const out: StepWords[] = [];
+  for (const entry of steps) {
+    if (entry === null || typeof entry !== "object") continue;
+    const step = entry as RecipeStep;
+    out.push(stepWords(step));
+    const nested = step as unknown as { then?: unknown; else?: unknown; steps?: unknown };
+    for (const key of ["then", "else", "steps"] as const) {
+      const inner = nested[key];
+      if (Array.isArray(inner)) out.push(...stepWordsList(inner));
+    }
+  }
+  return out;
+}
diff --git a/apps/web/src/pages/RunDetail.tsx b/apps/web/src/pages/RunDetail.tsx
index 6ffe97c..cd721b1 100644
--- a/apps/web/src/pages/RunDetail.tsx
+++ b/apps/web/src/pages/RunDetail.tsx
@@ -1,6 +1,272 @@
-import { EmptyState } from "../shell/EmptyState";
+import { type CSSProperties, useEffect, useState } from "react";
+import { Link, useParams } from "react-router-dom";
 
-/** Placeholder: builder C replaces this file with the run page: progress and results. */
+import { apiPost, errorText } from "../lib/api";
+import { useJson } from "../lib/useJson";
+import {
+  isOpenStatus,
+  minutesSavedWords,
+  pauseReasonWords,
+  plainReason,
+  rowOutcome,
+  runActions,
+  runStatusWords,
+} from "../lib/words";
+import type { RecordRow, RunDetail as RunDetailPayload } from "../types";
+import "./runs.css";
+
+type RunAction = "pause" | "resume" | "cancel";
+
+/** The blur-in stagger for the sections (DESIGN.md §7). */
+function slot(index: number): CSSProperties {
+  return { "--i": index } as CSSProperties;
+}
+
+/** The rows of a run that are finished: added rows plus rows that were already there. */
+function doneCount(counts: Record<string, number>): number {
+  return (counts.verified ?? 0) + (counts.skipped ?? 0);
+}
+
+/** The run's rows. `GET /api/v1/runs/{id}` counts every state and carries the explicit total. */
+function totalCount(counts: Record<string, number>): number {
+  const explicit = counts.total;
+  if (typeof explicit === "number") return explicit;
+  return Object.values(counts).reduce((sum, value) => sum + value, 0);
+}
+
+/** A time a person can read, only when the API sent one. */
+function stamp(iso: string | null | undefined): string | null {
+  if (iso === null || iso === undefined || iso.trim() === "") return null;
+  const at = new Date(iso);
+  if (Number.isNaN(at.getTime())) return null;
+  return at.toLocaleString();
+}
+
+/**
+ * What the reason column says for one row.
+ *
+ * A row that finished has nothing to explain, so an empty reason stays empty instead of being
+ * filled in with a sentence that is not true about it. A row that needs a person always says
+ * something, so the fallback belongs there and only there.
+ */
+function reasonWords(row: RecordRow, needsHelp: boolean): string | null {
+  const written = (row.reason ?? "").trim();
+  if (written !== "") return plainReason(row.reason, row.state);
+  return needsHelp ? plainReason(null, row.state) : null;
+}
+
+/** One run: live progress, its buttons, and what every row ended up as. */
 export function RunDetail(): JSX.Element {
-  return <EmptyState sentence="This run's progress and results will appear here." />;
+  const { id } = useParams<{ id: string }>();
+  const runPath = id === undefined ? null : `/api/v1/runs/${id}`;
+  const recordsPath = id === undefined ? null : `/api/v1/runs/${id}/records`;
+
+  // The poll is 2 s while the run is still going, and `null` the moment it is not, so a finished
+  // run makes no further requests (PL-015's verified behaviour, carried forward).
+  const [pollMs, setPollMs] = useState<number | null>(2000);
+  const run = useJson<RunDetailPayload>(runPath, pollMs);
+  const records = useJson<RecordRow[]>(recordsPath, pollMs);
+
+  const detail = run.data;
+  const rows = records.data ?? [];
+  const open = isOpenStatus(detail?.status ?? null);
+
+  useEffect(() => {
+    const next = isOpenStatus(detail?.status ?? null) ? 2000 : null;
+    setPollMs((current) => (current === next ? current : next));
+  }, [detail]);
+
+  const [busy, setBusy] = useState<RunAction | null>(null);
+  const [refusal, setRefusal] = useState<{ action: RunAction; text: string } | null>(null);
+
+  async function act(action: RunAction): Promise<void> {
+    if (id === undefined) return;
+    setBusy(action);
+    setRefusal(null);
+    try {
+      await apiPost(`/api/v1/runs/${id}/${action}`);
+      run.reload();
+    } catch (failure) {
+      // The API's own `detail` text, shown next to the button that caused it.
+      setRefusal({ action, text: errorText(failure) });
+    } finally {
+      setBusy(null);
+    }
+  }
+
+  if (detail === null || typeof detail.status !== "string") {
+    return (
+      <div className="run-detail">
+        <p className="lede in" style={slot(1)}>
+          {run.error ?? "Loading this run…"}
+        </p>
+      </div>
+    );
+  }
+
+  const status = runStatusWords(detail.status);
+  const buttons = runActions(detail.status);
+  // Every count comes from the API, and a run with no records counts as nothing at all.
+  const counts = (detail.counts ?? {}) as Record<string, number>;
+  const done = doneCount(counts);
+  const total = totalCount(counts);
+  const alreadyThere = counts.skipped ?? 0;
+  const pauseReason = pauseReasonWords(detail.pause_reason);
+  const started = stamp(detail.started_at);
+  const finished = stamp(detail.finished_at);
+
+  // "About 52 minutes saved": the rows this run finished would have taken about three minutes each
+  // by hand, less the wall-clock the run itself took. Only a finished run has both times.
+  const minutes =
+    detail.started_at != null && detail.finished_at != null
+      ? (new Date(detail.finished_at).getTime() - new Date(detail.started_at).getTime()) / 60000
+      : null;
+  const saved = !open && minutes !== null ? minutesSavedWords(done * 3 - minutes) : null;
+
+  return (
+    <div className="run-detail">
+      <section className="panel in" style={slot(1)}>
+        <div className="panel-h">
+          <h3>Progress</h3>
+          {open ? (
+            <span className="live">
+              <i /> Live
+            </span>
+          ) : null}
+        </div>
+        <div className="run">
+          <b>
+            {done} of {total} done
+          </b>
+          <div className="track" aria-hidden="true">
+            <i style={{ width: `${total === 0 ? 0 : Math.round((done / total) * 100)}%` }} />
+          </div>
+          <div className="meta">
+            <span className={`res ${status.tone}`}>{status.label}</span>
+            <span>{alreadyThere} already there</span>
+          </div>
+        </div>
+        <p className="pause-reason">{pauseReason ?? "Not paused."}</p>
+        {started === null && finished === null ? null : (
+          <p className="times">
+            {started === null ? null : (
+              <span>
+                Started <time dateTime={detail.started_at ?? undefined}>{started}</time>
+              </span>
+            )}
+            {finished === null ? null : (
+              <span>
+                Finished <time dateTime={detail.finished_at ?? undefined}>{finished}</time>
+              </span>
+            )}
+          </p>
+        )}
+        <div className="actions">
+          {buttons.pause ? (
+            <>
+              <button
+                type="button"
+                className="btn quiet"
+                disabled={busy !== null}
+                onClick={() => void act("pause")}
+              >
+                Pause
+              </button>
+              {refusal?.action === "pause" ? (
+                <span className="refusal" role="status">
+                  {refusal.text}
+                </span>
+              ) : null}
+            </>
+          ) : null}
+          {buttons.resume ? (
+            <>
+              <button
+                type="button"
+                className="btn quiet"
+                disabled={busy !== null}
+                onClick={() => void act("resume")}
+              >
+                Resume
+              </button>
+              {refusal?.action === "resume" ? (
+                <span className="refusal" role="status">
+                  {refusal.text}
+                </span>
+              ) : null}
+            </>
+          ) : null}
+          {buttons.cancel ? (
+            <>
+              <button
+                type="button"
+                className="btn quiet"
+                disabled={busy !== null}
+                onClick={() => void act("cancel")}
+              >
+                Cancel
+              </button>
+              {refusal?.action === "cancel" ? (
+                <span className="refusal" role="status">
+                  {refusal.text}
+                </span>
+              ) : null}
+            </>
+          ) : null}
+          <a className="btn quiet export" href={`/api/v1/runs/${detail.id}/results.csv`}>
+            Export CSV
+          </a>
+        </div>
+      </section>
+
+      {saved === null ? null : (
+        <section className="saved-fig in" style={slot(2)}>
+          <b>{saved}</b>
+          <span>Time saved</span>
+          <small>vs. about 3 minutes a row by hand</small>
+        </section>
+      )}
+
+      <section className="panel in" style={slot(3)}>
+        <div className="panel-h">
+          <h3>What happened to each row</h3>
+          <Link to="/needs-help">Needs help</Link>
+        </div>
+        {rows.length === 0 ? (
+          <p className="panel-note">
+            {records.error ?? "The rows of this run will appear here."}
+          </p>
+        ) : (
+          <table>
+            <thead>
+              <tr>
+                <th>Row</th>
+                <th>Result</th>
+                <th>Reason</th>
+              </tr>
+            </thead>
+            <tbody>
+              {rows.map((row) => {
+                const outcome = rowOutcome(row.state);
+                const reason = reasonWords(row, outcome.tone === "help");
+                return (
+                  <tr key={row.id}>
+                    {/* A row's key is the person's or thing's name for that row; it is data, so it
+                        is rendered as text and never as markup. */}
+                    <td>
+                      <b>{row.record_key}</b>
+                    </td>
+                    <td>
+                      <span className={`res ${outcome.tone}`}>{outcome.label}</span>
+                    </td>
+                    <td>{reason ?? "—"}</td>
+                  </tr>
+                );
+              })}
+            </tbody>
+          </table>
+        )}
+      </section>
+    </div>
+  );
 }
diff --git a/apps/web/src/pages/Runs.tsx b/apps/web/src/pages/Runs.tsx
index 9cb467c..f368ae8 100644
--- a/apps/web/src/pages/Runs.tsx
+++ b/apps/web/src/pages/Runs.tsx
@@ -1,6 +1,123 @@
-import { EmptyState } from "../shell/EmptyState";
+import { type CSSProperties, useEffect, useState } from "react";
+import { Link } from "react-router-dom";
 
-/** Placeholder: builder C replaces this file with the list of every run, live and past. */
+import { useJson } from "../lib/useJson";
+import { isOpenStatus, relativeTime, runStatusWords } from "../lib/words";
+import type { RunSummary } from "../types";
+import "./runs.css";
+
+/** The blur-in stagger: the header and the table rise 70 ms apart (DESIGN.md §7). */
+function slot(index: number): CSSProperties {
+  return { "--i": index } as CSSProperties;
+}
+
+/** The rows of a run that are finished: added rows plus rows that were already there. */
+function doneCount(counts: Record<string, number>): number {
+  return (counts.verified ?? 0) + (counts.skipped ?? 0);
+}
+
+/** The run's rows: the per-state counts sum to the total (there is no `total` key in this list). */
+function totalCount(counts: Record<string, number>): number {
+  return Object.values(counts).reduce((sum, value) => sum + value, 0);
+}
+
+/** Every run, live and past. */
 export function Runs(): JSX.Element {
-  return <EmptyState sentence="Every run, live and past, will appear here." />;
+  // A run that is still going keeps the list live; the moment none is, `pollMs` is null and the
+  // interval stops, so a settled list makes no further requests.
+  const [live, setLive] = useState(false);
+  const { data, error } = useJson<RunSummary[]>("/api/v1/runs", live ? 2000 : null);
+
+  // The API always answers with a list, but a refusal or a stubbed response is not one, so the
+  // page never assumes the shape and shows one sentence instead of throwing.
+  const rows = Array.isArray(data) ? data : null;
+
+  useEffect(() => {
+    setLive((rows ?? []).some((run) => isOpenStatus(run.status)));
+  }, [rows]);
+
+  if (rows === null) {
+    return (
+      <div className="runs">
+        <p className="lede in" style={slot(1)}>
+          {error ?? "Loading your runs…"}
+        </p>
+      </div>
+    );
+  }
+
+  if (rows.length === 0) {
+    return (
+      <div className="runs">
+        <section className="panel in" style={slot(1)}>
+          <div className="empty">
+            <p className="empty-sentence">
+              Nothing has run yet. When a task runs, it appears here with what it did.
+            </p>
+            <p className="empty-action">
+              <Link className="btn quiet" to="/tasks">
+                Go to your tasks
+              </Link>
+            </p>
+          </div>
+        </section>
+      </div>
+    );
+  }
+
+  return (
+    <div className="runs">
+      <section className="panel in" style={slot(1)}>
+        <div className="panel-h">
+          <h3>All runs</h3>
+          {live ? (
+            <span className="live">
+              <i /> Live
+            </span>
+          ) : null}
+        </div>
+        <table>
+          <thead>
+            <tr>
+              <th>Task</th>
+              <th>Started</th>
+              <th>Status</th>
+              <th>Progress</th>
+              <th />
+            </tr>
+          </thead>
+          <tbody>
+            {rows.map((run) => {
+              const outcome = runStatusWords(run.status);
+              const counts = run.counts ?? {};
+              const done = doneCount(counts);
+              const total = totalCount(counts);
+              return (
+                <tr key={run.id}>
+                  <td>
+                    <b>{run.recipe_name ?? "This task"}</b>
+                  </td>
+                  <td>{relativeTime(run.created_at)}</td>
+                  <td>
+                    <span className={`res ${outcome.tone}`}>{outcome.label}</span>
+                  </td>
+                  <td className="progress-cell">
+                    {done} of {total} done
+                    <span className="track" aria-hidden="true">
+                      <i style={{ width: `${total === 0 ? 0 : Math.round((done / total) * 100)}%` }} />
+                    </span>
+                  </td>
+                  <td className="act">
+                    <Link className="btn quiet" to={`/runs/${run.id}`}>
+                      Open
+                    </Link>
+                  </td>
+                </tr>
+              );
+            })}
+          </tbody>
+        </table>
+      </section>
+    </div>
+  );
 }
diff --git a/apps/web/src/pages/TaskDetail.tsx b/apps/web/src/pages/TaskDetail.tsx
index cca787b..a1b5d67 100644
--- a/apps/web/src/pages/TaskDetail.tsx
+++ b/apps/web/src/pages/TaskDetail.tsx
@@ -1,6 +1,148 @@
-import { EmptyState } from "../shell/EmptyState";
+import { type CSSProperties } from "react";
+import { Link, useParams } from "react-router-dom";
 
-/** Placeholder: builder C replaces this file with the task page (steps in plain words, and runs). */
+import { stepWordsList, type RecipeStep } from "../lib/steps";
+import { useJson } from "../lib/useJson";
+import { relativeTime, runStatusWords } from "../lib/words";
+import type { RunSummary, TaskRow } from "../types";
+import "./tasks.css";
+
+/**
+ * `GET /api/v1/recipes/{id}`: the stored recipe version, with its document under `recipe` and the
+ * task's name beside it. The shape is in `services/api/recipes.py` (`RecipeVersionDetail`); the
+ * pages own only the fields they read.
+ */
+interface RecipeResponse {
+  id: string;
+  workflow_id: string;
+  workflow_name: string;
+  version: number;
+  name: string;
+  recipe: { steps?: RecipeStep[] } | null;
+}
+
+/** The blur-in stagger for the sections (DESIGN.md §7). */
+function slot(index: number): CSSProperties {
+  return { "--i": index } as CSSProperties;
+}
+
+/** How many of a run's rows are finished: the ones added and the ones already there. */
+function doneCount(counts: Record<string, number>): number {
+  return (counts.verified ?? 0) + (counts.skipped ?? 0);
+}
+
+function totalCount(counts: Record<string, number>): number {
+  return Object.values(counts).reduce((sum, value) => sum + value, 0);
+}
+
+/**
+ * One task, read only for now: its steps in plain words and its runs. The editor arrives in a later
+ * ticket, so this page shows and changes nothing.
+ */
 export function TaskDetail(): JSX.Element {
-  return <EmptyState sentence="This task's steps and its runs will appear here." />;
+  const { id } = useParams<{ id: string }>();
+
+  // The page needs the task's name, its site and the id of the recipe version it is running, and
+  // `GET /api/v1/tasks` carries all three: one task out of that list is the whole lookup.
+  const tasks = useJson<TaskRow[]>("/api/v1/tasks");
+  const task = (Array.isArray(tasks.data) ? tasks.data : []).find(
+    (entry) => entry.workflow_id === id,
+  ) ?? null;
+  const recipe = useJson<RecipeResponse>(
+    task === null ? null : `/api/v1/recipes/${task.recipe_version_id}`,
+  );
+  // The runs list has no task id, only the name it was run under, so a task's runs are matched on
+  // that name. It is the same string `GET /api/v1/tasks` shows, so this stays simple on purpose.
+  const runs = useJson<RunSummary[]>("/api/v1/runs");
+
+  if (task === null) {
+    const settled = Array.isArray(tasks.data);
+    return (
+      <div className="task-detail">
+        <p className="lede in" style={slot(1)}>
+          {settled ? "This task could not be found." : (tasks.error ?? "Loading this task…")}
+        </p>
+      </div>
+    );
+  }
+
+  const steps = stepWordsList(recipe.data?.recipe?.steps);
+  const mine = (Array.isArray(runs.data) ? runs.data : []).filter(
+    (run) => run.recipe_name === task.name,
+  );
+
+  return (
+    <div className="task-detail">
+      <section className="hero in" style={slot(1)}>
+        <div>
+          <h1 className="big">{task.name}</h1>
+          <p className="lede">{task.app ?? "No site yet"}</p>
+        </div>
+      </section>
+
+      <section className="two">
+        <div className="panel in" style={slot(2)}>
+          <div className="panel-h">
+            <h3>Steps</h3>
+          </div>
+          {steps.length === 0 ? (
+            <p className="panel-note">
+              {recipe.error ?? "The steps of this task will appear here."}
+            </p>
+          ) : (
+            <ol className="steps">
+              {steps.map((step, index) => (
+                <li key={index}>
+                  <b>{step.title}</b>
+                  {step.detail === undefined ? null : <small>{step.detail}</small>}
+                </li>
+              ))}
+            </ol>
+          )}
+          <p className="panel-note">You cannot change these steps yet.</p>
+        </div>
+
+        <div className="panel in" style={slot(3)}>
+          <div className="panel-h">
+            <h3>Runs</h3>
+            <Link to="/runs">See all</Link>
+          </div>
+          {mine.length === 0 ? (
+            <p className="panel-note">This task has not run yet.</p>
+          ) : (
+            <table>
+              <thead>
+                <tr>
+                  <th>Started</th>
+                  <th>Result</th>
+                  <th />
+                </tr>
+              </thead>
+              <tbody>
+                {mine.map((run) => {
+                  const outcome = runStatusWords(run.status);
+                  return (
+                    <tr key={run.id}>
+                      <td>{relativeTime(run.created_at)}</td>
+                      <td>
+                        <span className={`res ${outcome.tone}`}>{outcome.label}</span>
+                        <small>
+                          {doneCount(run.counts ?? {})} of {totalCount(run.counts ?? {})} done
+                        </small>
+                      </td>
+                      <td className="act">
+                        <Link className="btn quiet" to={`/runs/${run.id}`}>
+                          Open
+                        </Link>
+                      </td>
+                    </tr>
+                  );
+                })}
+              </tbody>
+            </table>
+          )}
+        </div>
+      </section>
+    </div>
+  );
 }
diff --git a/apps/web/src/pages/Tasks.tsx b/apps/web/src/pages/Tasks.tsx
index 0738232..bfef63b 100644
--- a/apps/web/src/pages/Tasks.tsx
+++ b/apps/web/src/pages/Tasks.tsx
@@ -1,6 +1,123 @@
-import { EmptyState } from "../shell/EmptyState";
+import { type CSSProperties } from "react";
+import { Link } from "react-router-dom";
 
-/** Placeholder: builder C replaces this file with the Tasks list of the approved mock. */
+import { useJson } from "../lib/useJson";
+import { isOpenStatus, relativeTime, runStatusWords } from "../lib/words";
+import type { TaskRow } from "../types";
+import "./tasks.css";
+
+/** The blur-in stagger: the header and the table rise 70 ms apart (DESIGN.md §7). */
+function slot(index: number): CSSProperties {
+  return { "--i": index } as CSSProperties;
+}
+
+/**
+ * The one quiet button a task row offers. The run flow arrives in a later ticket, so both "Run
+ * again" and "Try one row" open the task page rather than starting a run. The Shell already draws
+ * the page's one primary action ("Teach a new task"), so these stay quiet.
+ */
+function taskAction(task: TaskRow): { label: string; to: string } {
+  if (task.last_run === null || task.last_run === undefined) {
+    return { label: "Try one row", to: `/tasks/${task.workflow_id}` };
+  }
+  if (task.last_run.status === "running") {
+    return { label: "Open", to: `/runs/${task.last_run.run_id}` };
+  }
+  return { label: "Run again", to: `/tasks/${task.workflow_id}` };
+}
+
+/** A task's result in plain words, never a state name (DESIGN.md §2). */
+function taskResult(task: TaskRow): { label: string; tone: string } {
+  const run = task.last_run;
+  if (run === null || run === undefined) return { label: "Ready", tone: "idle" };
+  const parked = run.counts?.parked ?? 0;
+  const failed = run.counts?.failed ?? 0;
+  if (isOpenStatus(run.status)) {
+    const outcome = runStatusWords(run.status);
+    return { label: outcome.label, tone: outcome.tone };
+  }
+  if (failed > 0) return { label: "Didn't work", tone: "help" };
+  if (parked > 0) return { label: `${parked} needs help`, tone: "help" };
+  const outcome = runStatusWords(run.status);
+  return { label: outcome.label, tone: outcome.tone };
+}
+
+/** Every task that has been taught, in one table. */
 export function Tasks(): JSX.Element {
-  return <EmptyState sentence="Your saved tasks will appear here." />;
+  const { data, error } = useJson<TaskRow[]>("/api/v1/tasks");
+  // A refusal (or a stubbed answer that is not a list) shows one sentence instead of throwing.
+  const rows = Array.isArray(data) ? data : null;
+
+  if (rows === null) {
+    return (
+      <div className="tasks">
+        <p className="lede in" style={slot(1)}>
+          {error ?? "Loading your tasks…"}
+        </p>
+      </div>
+    );
+  }
+
+  if (rows.length === 0) {
+    return (
+      <div className="tasks">
+        <section className="panel in" style={slot(1)}>
+          <div className="empty">
+            <p className="empty-sentence">The tasks you teach will appear here.</p>
+            <p className="empty-action">
+              <Link className="btn quiet" to="/teach">
+                Teach your first task
+              </Link>
+            </p>
+          </div>
+        </section>
+      </div>
+    );
+  }
+
+  return (
+    <div className="tasks">
+      <section className="panel in" style={slot(1)}>
+        <div className="panel-h">
+          <h3>Your tasks</h3>
+          <span className="count">{rows.length} saved</span>
+        </div>
+        <table>
+          <thead>
+            <tr>
+              <th>Task</th>
+              <th>Last run</th>
+              <th>Result</th>
+              <th />
+            </tr>
+          </thead>
+          <tbody>
+            {rows.map((task) => {
+              const action = taskAction(task);
+              const result = taskResult(task);
+              return (
+                <tr key={task.workflow_id}>
+                  <td>
+                    <Link className="task-name" to={`/tasks/${task.workflow_id}`}>
+                      {task.name}
+                    </Link>
+                    <small>{task.app ?? "No site yet"}</small>
+                  </td>
+                  <td>{relativeTime(task.last_run?.started_at ?? null)}</td>
+                  <td>
+                    <span className={`res ${result.tone}`}>{result.label}</span>
+                  </td>
+                  <td className="act">
+                    <Link className="btn quiet" to={action.to}>
+                      {action.label}
+                    </Link>
+                  </td>
+                </tr>
+              );
+            })}
+          </tbody>
+        </table>
+      </section>
+    </div>
+  );
 }
diff --git a/apps/web/src/pages/runs.css b/apps/web/src/pages/runs.css
new file mode 100644
index 0000000..929a062
--- /dev/null
+++ b/apps/web/src/pages/runs.css
@@ -0,0 +1,92 @@
+/* Runs' own placement. The panels, rows, tables, progress bars, live dot and buttons are already
+   ported into styles/global.css from the approved mock, so nothing here duplicates them. */
+
+.runs,
+.run-detail {
+  display: grid;
+  gap: 30px;
+  align-content: start;
+}
+
+.runs .empty {
+  padding: 8px 20px 20px;
+}
+
+.runs .empty-sentence {
+  margin: 0;
+  color: var(--ink-2);
+  font-size: 14.5px;
+}
+
+.runs .empty-action {
+  margin: 14px 0 0;
+}
+
+/* "11 of 20 done" over a thin progress bar: the same bar Home shows, with the words under it. */
+.runs td.progress-cell {
+  font-variant-numeric: tabular-nums;
+}
+
+.runs td.progress-cell .track {
+  display: block;
+  margin-top: 7px;
+  max-width: 180px;
+}
+
+.run-detail .pause-reason {
+  margin: 0;
+  padding: 0 20px 14px;
+  color: var(--ink-2);
+  font-size: 14px;
+}
+
+.run-detail .times {
+  margin: 0;
+  padding: 0 20px 14px;
+  display: flex;
+  gap: 18px;
+  flex-wrap: wrap;
+  color: var(--muted);
+  font-size: 13px;
+  font-variant-numeric: tabular-nums;
+}
+
+.run-detail .actions {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  flex-wrap: wrap;
+  padding: 0 20px 18px;
+}
+
+/* A refusal sits next to the button that caused it, so a person knows what to do next. */
+.run-detail .refusal {
+  color: var(--help);
+  font-size: 13.5px;
+}
+
+.run-detail .export {
+  margin-left: auto;
+}
+
+.run-detail .panel-note {
+  margin: 0;
+  padding: 12px 20px 20px;
+  color: var(--ink-2);
+  font-size: 14px;
+}
+
+.run-detail .saved-fig {
+  justify-self: start;
+  min-width: 200px;
+}
+
+@media (max-width: 780px) {
+  .run-detail .export {
+    margin-left: 0;
+  }
+
+  .runs .empty {
+    padding: 4px 16px 18px;
+  }
+}
diff --git a/apps/web/src/pages/tasks.css b/apps/web/src/pages/tasks.css
new file mode 100644
index 0000000..dea503d
--- /dev/null
+++ b/apps/web/src/pages/tasks.css
@@ -0,0 +1,91 @@
+/* Tasks' own placement. The panels, rows, tables, dots and buttons are already ported into
+   styles/global.css from the approved mock, so nothing here duplicates them. */
+
+.tasks,
+.task-detail {
+  display: grid;
+  gap: 30px;
+  align-content: start;
+}
+
+.tasks .empty,
+.task-detail .empty {
+  padding: 8px 20px 20px;
+}
+
+.tasks .empty-sentence,
+.task-detail .empty-sentence {
+  margin: 0;
+  color: var(--ink-2);
+  font-size: 14.5px;
+}
+
+.tasks .empty-action {
+  margin: 14px 0 0;
+}
+
+.tasks .count {
+  color: var(--muted);
+  font-size: 13px;
+}
+
+/* A task's name is the way into the task, so it reads as the row's title rather than a link. */
+.tasks a.task-name {
+  color: var(--ink);
+  font-weight: 500;
+  text-decoration: none;
+  display: block;
+}
+
+.tasks a.task-name:hover {
+  text-decoration: underline;
+}
+
+.task-detail .panel-note {
+  margin: 0;
+  padding: 12px 20px 20px;
+  color: var(--ink-2);
+  font-size: 14px;
+}
+
+/* The steps: one sentence each, in the order the run follows them. */
+.task-detail ol.steps {
+  list-style: none;
+  margin: 0;
+  padding: 0 0 6px;
+  counter-reset: step;
+}
+
+.task-detail ol.steps li {
+  counter-increment: step;
+  padding: 12px 20px;
+  border-top: 1px solid var(--hair);
+}
+
+.task-detail ol.steps li:first-child {
+  border-top: 0;
+}
+
+.task-detail ol.steps li b::before {
+  content: counter(step) ". ";
+  color: var(--muted);
+  font-weight: 400;
+  font-variant-numeric: tabular-nums;
+}
+
+.task-detail ol.steps b {
+  font-weight: 500;
+}
+
+.task-detail ol.steps small {
+  display: block;
+  color: var(--muted);
+  font-size: 13px;
+}
+
+@media (max-width: 780px) {
+  .tasks .empty,
+  .task-detail .empty {
+    padding: 4px 16px 18px;
+  }
+}
diff --git a/apps/web/tests/runs.test.tsx b/apps/web/tests/runs.test.tsx
new file mode 100644
index 0000000..d55b94b
--- /dev/null
+++ b/apps/web/tests/runs.test.tsx
@@ -0,0 +1,300 @@
+/**
+ * The runs list and one run: the buttons follow the status, a refusal sits next to the button that
+ * caused it, the pause reason is in words, and the live poll stops the moment the run is not open
+ * (PL-015's verified behaviour, carried forward).
+ */
+
+import { act, fireEvent, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import type { RecordRow, RunDetail as RunPayload, RunSummary } from "../src/types";
+import { callsTo, createFetchStub, renderApp, settle, type FetchStub } from "./helpers";
+
+/* Every path the Shell asks for as well, so a page test never hits the real API. */
+const SHELL = {
+  "/api/v1/needs-help": { body: [] },
+  "/api/v1/executor/session": { body: { attached: false } },
+};
+
+let stub: FetchStub | null = null;
+
+afterEach(() => {
+  stub?.restore();
+  stub = null;
+  vi.useRealTimers();
+});
+
+function runSummary(overrides: Partial<RunSummary> = {}): RunSummary {
+  return {
+    id: "run-1",
+    status: "running",
+    pause_reason: null,
+    created_at: new Date().toISOString(),
+    recipe_name: "Add inquiries",
+    recipe_version: "3",
+    counts: { verified: 11, pending: 9 },
+    ...overrides,
+  };
+}
+
+function runDetail(overrides: Partial<RunPayload> = {}): RunPayload {
+  return {
+    id: "run-1",
+    status: "running",
+    pause_reason: null,
+    counts: { total: 20, verified: 11, skipped: 0, parked: 0, failed: 0, in_progress: 9 },
+    open_approval: null,
+    started_at: null,
+    finished_at: null,
+    ...overrides,
+  };
+}
+
+function record(overrides: Partial<RecordRow> = {}): RecordRow {
+  return {
+    id: "rr-1",
+    record_key: "priya@example.com",
+    state: "verified",
+    reason: null,
+    attempts: 1,
+    max_attempts: 3,
+    commit_attempted: false,
+    destination_ref: null,
+    ...overrides,
+  };
+}
+
+function buttonNames(): string[] {
+  return screen
+    .getAllByRole("button")
+    .map((node) => node.textContent ?? "")
+    .filter((label) => ["Pause", "Resume", "Cancel"].includes(label));
+}
+
+describe("the runs list", () => {
+  it("shows the task, when it started, what it is doing and how far it got", async () => {
+    stub = createFetchStub({
+      ...SHELL,
+      "/api/v1/runs": { body: [runSummary()] },
+    });
+    renderApp("/runs");
+    await settle();
+
+    expect(screen.getByText("Add inquiries")).toBeTruthy();
+    expect(screen.getAllByText("Running").length).toBeGreaterThan(0);
+    expect(screen.getByText("11 of 20 done")).toBeTruthy();
+    expect(screen.getByRole("link", { name: "Open" }).getAttribute("href")).toBe("/runs/run-1");
+  });
+
+  it("counts a row that was already there as done", async () => {
+    stub = createFetchStub({
+      ...SHELL,
+      "/api/v1/runs": {
+        body: [runSummary({ status: "completed", counts: { verified: 4, skipped: 6 } })],
+      },
+    });
+    renderApp("/runs");
+    await settle();
+
+    expect(screen.getByText("10 of 10 done")).toBeTruthy();
+    expect(screen.getAllByText("Finished").length).toBeGreaterThan(0);
+  });
+
+  it("says what will appear here and points at the tasks when nothing has run", async () => {
+    stub = createFetchStub({ ...SHELL, "/api/v1/runs": { body: [] } });
+    renderApp("/runs");
+    await settle();
+
+    expect(screen.getByText(/Nothing has run yet/)).toBeTruthy();
+    expect(screen.getByRole("link", { name: "Go to your tasks" }).getAttribute("href")).toBe(
+      "/tasks",
+    );
+  });
+});
+
+describe("one run", () => {
+  it("offers Pause and Cancel while it is going, Resume only when it is paused", async () => {
+    stub = createFetchStub({
+      ...SHELL,
+      "/api/v1/runs/run-1/records": { body: [] },
+      "/api/v1/runs/run-1": { body: runDetail({ status: "running" }) },
+    });
+    const first = renderApp("/runs/run-1");
+    await settle();
+    expect(buttonNames()).toEqual(["Pause", "Cancel"]);
+    first.unmount();
+    stub.restore();
+
+    stub = createFetchStub({
+      ...SHELL,
+      "/api/v1/runs/run-1/records": { body: [] },
+      "/api/v1/runs/run-1": { body: runDetail({ status: "paused", pause_reason: "login_required" }) },
+    });
+    renderApp("/runs/run-1");
+    await settle();
+    expect(buttonNames()).toEqual(["Pause", "Resume", "Cancel"]);
+  });
+
+  it("offers nothing once the run is finished", async () => {
+    stub = createFetchStub({
+      ...SHELL,
+      "/api/v1/runs/run-1/records": { body: [] },
+      "/api/v1/runs/run-1": { body: runDetail({ status: "completed" }) },
+    });
+    renderApp("/runs/run-1");
+    await settle();
+
+    expect(buttonNames()).toEqual([]);
+  });
+
+  it("puts the pause reason into words, and says so when there is none", async () => {
+    stub = createFetchStub({
+      ...SHELL,
+      "/api/v1/runs/run-1/records": { body: [] },
+      "/api/v1/runs/run-1": { body: runDetail({ status: "paused", pause_reason: "login_required" }) },
+    });
+    const paused = renderApp("/runs/run-1");
+    await settle();
+
+    expect(
+      screen.getByText("Log in to the site in the bound tab, then resume."),
+    ).toBeTruthy();
+    paused.unmount();
+    stub.restore();
+
+    stub = createFetchStub({
+      ...SHELL,
+      "/api/v1/runs/run-1/records": { body: [] },
+      "/api/v1/runs/run-1": { body: runDetail({ status: "running" }) },
+    });
+    renderApp("/runs/run-1");
+    await settle();
+    expect(screen.getByText("Not paused.")).toBeTruthy();
+  });
+
+  it("shows every row's name, its result and its reason, and leaves a finished row's reason empty", async () => {
+    stub = createFetchStub({
+      ...SHELL,
+      "/api/v1/runs/run-1/records": {
+        body: [
+          record(),
+          record({ id: "rr-2", record_key: "sam@example.com", state: "parked", reason: "missing email" }),
+          record({ id: "rr-3", record_key: "kim@example.com", state: "skipped", reason: null }),
+          record({ id: "rr-4", record_key: "lee@example.com", state: "parked", reason: null }),
+        ],
+      },
+      "/api/v1/runs/run-1": { body: runDetail() },
+    });
+    renderApp("/runs/run-1");
+    await settle();
+
+    expect(screen.getByText("priya@example.com")).toBeTruthy();
+    expect(screen.getByText("sam@example.com")).toBeTruthy();
+    expect(screen.getAllByText("Done").length).toBeGreaterThan(0);
+    expect(screen.getAllByText("Needs your help").length).toBeGreaterThan(0);
+    expect(screen.getAllByText("Already there").length).toBeGreaterThan(0);
+    expect(screen.getByText("Missing email.")).toBeTruthy();
+    // A row that needs a person always says something; a row that finished has nothing to explain,
+    // so its reason is a dash and never a sentence that is not true about it.
+    expect(screen.getByText("Something went wrong.")).toBeTruthy();
+    const row = screen.getByText("priya@example.com").closest("tr");
+    expect(row?.textContent).not.toContain("Something went wrong");
+  });
+
+  it("exports the results from this origin", async () => {
+    stub = createFetchStub({
+      ...SHELL,
+      "/api/v1/runs/run-1/records": { body: [] },
+      "/api/v1/runs/run-1": { body: runDetail({ status: "completed" }) },
+    });
+    renderApp("/runs/run-1");
+    await settle();
+
+    expect(screen.getByRole("link", { name: "Export CSV" }).getAttribute("href")).toBe(
+      "/api/v1/runs/run-1/results.csv",
+    );
+  });
+
+  it("shows a refusal next to the button that caused it", async () => {
+    stub = createFetchStub({
+      ...SHELL,
+      "/api/v1/runs/run-1/records": { body: [] },
+      "/api/v1/runs/run-1/pause": { status: 409, body: { detail: "run run-1 is completed" } },
+      "/api/v1/runs/run-1": { body: runDetail({ status: "running" }) },
+    });
+    renderApp("/runs/run-1");
+    await settle();
+
+    await act(async () => {
+      fireEvent.click(screen.getByRole("button", { name: "Pause" }));
+    });
+    await settle();
+
+    expect(screen.getByText("run run-1 is completed")).toBeTruthy();
+  });
+
+  it("shows the times and the time saved for a finished run", async () => {
+    stub = createFetchStub({
+      ...SHELL,
+      "/api/v1/runs/run-1/records": { body: [] },
+      "/api/v1/runs/run-1": {
+        body: runDetail({
+          status: "completed",
+          started_at: "2026-10-15T09:00:00Z",
+          finished_at: "2026-10-15T09:52:00Z",
+          counts: { total: 20, verified: 20, skipped: 0, parked: 0, failed: 0, in_progress: 0 },
+        }),
+      },
+    });
+    renderApp("/runs/run-1");
+    await settle();
+
+    expect(screen.getByText(/Started/)).toBeTruthy();
+    expect(screen.getAllByText(/Finished/).length).toBeGreaterThan(0);
+    // 20 rows at about three minutes each, less the 52 minutes the run took.
+    expect(screen.getByText("About 8 minutes saved")).toBeTruthy();
+  });
+});
+
+describe("the page's poll", () => {
+  it("asks every two seconds while the run is open and stops for good once it finishes", async () => {
+    vi.useFakeTimers();
+    let status = "running";
+    const fetchStub = createFetchStub({
+      ...SHELL,
+      "/api/v1/runs/run-1/records": { body: [record()] },
+      "/api/v1/runs/run-1": () => ({ body: runDetail({ status }) }),
+    });
+    stub = fetchStub;
+
+    renderApp("/runs/run-1");
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(0);
+    });
+    const first = callsTo(fetchStub, "/api/v1/runs/run-1");
+    expect(first).toBeGreaterThan(0);
+    expect(screen.getByRole("button", { name: "Pause" })).toBeTruthy();
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(2000);
+    });
+    expect(callsTo(fetchStub, "/api/v1/runs/run-1")).toBeGreaterThan(first);
+
+    // The API now reports the run as finished: the next refresh must stop the poll for good.
+    status = "completed";
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(2000);
+    });
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(0);
+    });
+    expect(screen.queryByRole("button", { name: "Pause" })).toBeNull();
+
+    const afterFinish = callsTo(fetchStub, "/api/v1/runs/run-1");
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(10_000);
+    });
+    expect(callsTo(fetchStub, "/api/v1/runs/run-1")).toBe(afterFinish);
+  });
+});
+
diff --git a/apps/web/tests/steps.test.ts b/apps/web/tests/steps.test.ts
new file mode 100644
index 0000000..7266950
--- /dev/null
+++ b/apps/web/tests/steps.test.ts
@@ -0,0 +1,145 @@
+/** The step sentences: one sentence per action, never a selector, never an id (plan §5). */
+
+import { readFileSync } from "node:fs";
+
+import { describe, expect, it } from "vitest";
+
+import { stepWords, stepWordsList } from "../src/lib/steps";
+
+const EXAMPLE = "../../packages/recipe/examples/create-lead.recipe.json";
+
+interface ExampleDocument {
+  steps: unknown[];
+}
+
+function exampleDocument(): ExampleDocument {
+  return JSON.parse(readFileSync(EXAMPLE, "utf8")) as ExampleDocument;
+}
+
+describe("a real recorded task", () => {
+  it("turns every step of the example recipe into one plain sentence", () => {
+    const document = exampleDocument();
+    const sentences = stepWordsList(document.steps).map((step) => step.title);
+
+    // Sixteen top-level steps, and the branch carries one of its own.
+    expect(sentences).toHaveLength(17);
+    expect(sentences[0]).toBe("Open the customer list");
+    expect(sentences).toContain("Type the email");
+    expect(sentences).toContain("Choose the interest");
+    expect(sentences).toContain("Click Save");
+    expect(sentences).toContain("Approve the first commit");
+    expect(sentences).toContain("Finish this row");
+  });
+
+  it("never lets an engine word, a step id, a test id or a selector reach the screen", () => {
+    const document = exampleDocument();
+    const sentences = stepWordsList(document.steps).map((step) => step.title);
+    for (const sentence of sentences) {
+      expect(sentence).not.toMatch(/[#{}]|\[/);
+      expect(sentence.toLowerCase()).not.toContain("lead-full-name");
+      expect(sentence.toLowerCase()).not.toContain("customer-search");
+      expect(sentence.toLowerCase()).not.toContain("step_");
+      expect(sentence.trim()).not.toBe("");
+    }
+  });
+});
+
+describe("a step without a name", () => {
+  it("opens the site the step navigates to", () => {
+    const step = { action: "navigate", url: "https://crm.example.com/new" };
+    expect(stepWords(step).title).toBe("Open crm.example.com");
+  });
+
+  it("reads the field's accessible name rather than its selector", () => {
+    const step = {
+      action: "fill",
+      targets: [{ by: "role", role: "textbox", name: "Email address" }],
+    };
+    expect(stepWords(step).title).toBe("Type the email address");
+  });
+
+  it("says only 'the field' when the ladder has nothing a person wrote", () => {
+    const step = {
+      action: "fill",
+      targets: [{ by: "css", selector: "#lead-email" }],
+      value: { kind: "input", column: "email" },
+    };
+    const sentence = stepWords(step).title;
+    expect(sentence).toBe("Type the field");
+    expect(sentence).not.toContain("#");
+    expect(sentence).not.toContain("email");
+  });
+
+  it("never shows a test id", () => {
+    const step = { action: "click", targets: [{ by: "testid", value: "lead-save" }] };
+    expect(stepWords(step).title).toBe("Click the button");
+  });
+
+  it("presses the key the step names", () => {
+    const step = {
+      action: "press",
+      key: "Enter",
+      targets: [{ by: "role", role: "button", name: "Search" }],
+    };
+    expect(stepWords(step).title).toBe("Press Enter");
+  });
+
+  it("says what each remaining action does", () => {
+    expect(stepWords({ action: "wait_for" }).title).toBe("Wait for the page");
+    expect(stepWords({ action: "assert" }).title).toBe("Check the result");
+    expect(stepWords({ action: "upload_file" }).title).toBe("Attach the file");
+    expect(stepWords({ action: "read_value" }).title).toBe("Read the value from the page");
+    expect(stepWords({ action: "download" }).title).toBe("Download the file");
+    expect(stepWords({ action: "extract" }).title).toBe("Read the details from the document");
+    expect(stepWords({ action: "classify" }).title).toBe("Choose the best answer");
+    expect(stepWords({ action: "approval_gate" }).title).toBe("Wait for your approval");
+    expect(stepWords({ action: "transform", op: "title_case" }).title).toBe("Work out the title case");
+    expect(stepWords({ action: "match", compare: "amount_within" }).title).toBe(
+      "Check the two amounts match",
+    );
+    expect(stepWords({ action: "aggregate", op: "sum" }).title).toBe("Add the values up");
+    expect(stepWords({ action: "branch", when: { url_matches: "/leads" } }).title).toBe(
+      "If the page has the right address, do the steps inside",
+    );
+    expect(stepWords({ action: "for_each", as: "line_item" }).title).toBe(
+      "For each line item, do the steps inside",
+    );
+  });
+
+  it("finishes a row the way the row ended", () => {
+    expect(stepWords({ action: "end_record", outcome: "verified" }).title).toBe("Finish this row");
+    expect(stepWords({ action: "end_record", outcome: "skipped" }).title).toBe(
+      "Mark this row as already there",
+    );
+  });
+
+  it("still says something for a step it has never seen", () => {
+    expect(stepWords({ action: "something_new" }).title).toBe("Do the next thing");
+  });
+});
+
+describe("a step's own name wins", () => {
+  it("uses the name the recipe author wrote", () => {
+    const step = {
+      action: "wait_for",
+      name: "The search box is usable",
+      targets: [{ by: "role", role: "textbox", name: "Search customers" }],
+    };
+    expect(stepWords(step).title).toBe("The search box is usable");
+  });
+
+  it("shows a value that is always typed, and nothing when it is a template", () => {
+    const withConstant = stepWords({
+      action: "select",
+      name: "Interest",
+      value: { kind: "constant", value: "New enquiry" },
+    });
+    expect(withConstant.detail).toBe("Always “New enquiry”");
+    const withTemplate = stepWords({
+      action: "select",
+      name: "Interest",
+      value: { kind: "constant", value: "{{interest_option}}" },
+    });
+    expect(withTemplate.detail).toBeUndefined();
+  });
+});
diff --git a/apps/web/tests/tasks.test.tsx b/apps/web/tests/tasks.test.tsx
new file mode 100644
index 0000000..48b51ff
--- /dev/null
+++ b/apps/web/tests/tasks.test.tsx
@@ -0,0 +1,129 @@
+/** The tasks a person has taught: what a person sees on the list, and the way into each task. */
+
+import { screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import type { TaskRow } from "../src/types";
+import { createFetchStub, renderApp, settle, type FetchStub } from "./helpers";
+
+/* Every path the Shell asks for as well, so a page test never hits the real API. */
+const SHELL = {
+  "/api/v1/needs-help": { body: [] },
+  "/api/v1/executor/session": { body: { attached: false } },
+};
+
+let stub: FetchStub | null = null;
+
+afterEach(() => {
+  stub?.restore();
+  stub = null;
+});
+
+function task(overrides: Partial<TaskRow> = {}): TaskRow {
+  return {
+    workflow_id: "wf-1",
+    recipe_version_id: "rv-1",
+    name: "Add inquiries",
+    app: "crm.example.com",
+    last_run: null,
+    ...overrides,
+  };
+}
+
+describe("the task list", () => {
+  it("shows each task, its site, its last run and its result", async () => {
+    const tasks: TaskRow[] = [
+      task(),
+      task({
+        workflow_id: "wf-2",
+        name: "Send invoices",
+        app: "billing.example.com",
+        last_run: {
+          run_id: "run-9",
+          status: "completed",
+          started_at: new Date().toISOString(),
+          counts: { verified: 4, skipped: 1 },
+        },
+      }),
+    ];
+    stub = createFetchStub({ ...SHELL, "/api/v1/tasks": { body: tasks } });
+    renderApp("/tasks");
+    await settle();
+
+    expect(screen.getByText("Add inquiries")).toBeTruthy();
+    expect(screen.getByText("crm.example.com")).toBeTruthy();
+    expect(screen.getAllByText("Ready").length).toBeGreaterThan(0);
+    expect(screen.getByText("Send invoices")).toBeTruthy();
+    expect(screen.getAllByText("Finished").length).toBeGreaterThan(0);
+    expect(screen.getByText("Now")).toBeTruthy();
+  });
+
+  it("offers 'Try one row' to a task that never ran and 'Run again' to one that did", async () => {
+    const tasks: TaskRow[] = [
+      task(),
+      task({
+        workflow_id: "wf-2",
+        name: "Send invoices",
+        last_run: {
+          run_id: "run-9",
+          status: "completed",
+          started_at: "2026-10-01T09:00:00Z",
+          counts: { verified: 4, skipped: 1 },
+        },
+      }),
+    ];
+    stub = createFetchStub({ ...SHELL, "/api/v1/tasks": { body: tasks } });
+    renderApp("/tasks");
+    await settle();
+
+    // The run flow arrives in a later ticket, so both labels open the task page.
+    const tryOne = screen.getByRole("link", { name: "Try one row" });
+    expect(tryOne.getAttribute("href")).toBe("/tasks/wf-1");
+    const again = screen.getByRole("link", { name: "Run again" });
+    expect(again.getAttribute("href")).toBe("/tasks/wf-2");
+  });
+
+  it("opens the task when its name is clicked", async () => {
+    stub = createFetchStub({ ...SHELL, "/api/v1/tasks": { body: [task()] } });
+    renderApp("/tasks");
+    await settle();
+
+    expect(screen.getByRole("link", { name: "Add inquiries" }).getAttribute("href")).toBe(
+      "/tasks/wf-1",
+    );
+  });
+
+  it("shows the task's own run while it is going", async () => {
+    stub = createFetchStub({
+      ...SHELL,
+      "/api/v1/tasks": {
+        body: [
+          task({
+            last_run: {
+              run_id: "run-9",
+              status: "running",
+              started_at: new Date().toISOString(),
+              counts: { verified: 3, skipped: 1, pending: 6 },
+            },
+          }),
+        ],
+      },
+    });
+    renderApp("/tasks");
+    await settle();
+
+    expect(screen.getByRole("link", { name: "Open" }).getAttribute("href")).toBe("/runs/run-9");
+    expect(screen.getAllByText("Running").length).toBeGreaterThan(0);
+  });
+
+  it("asks a person to teach a task when there are none", async () => {
+    stub = createFetchStub({ ...SHELL, "/api/v1/tasks": { body: [] } });
+    renderApp("/tasks");
+    await settle();
+
+    expect(screen.getByRole("link", { name: "Teach your first task" }).getAttribute("href")).toBe(
+      "/teach",
+    );
+    expect(screen.getByText(/will appear here/)).toBeTruthy();
+  });
+});

From 413b5005449797c974a973cfb809cd0c55f623e0 Mon Sep 17 00:00:00 2001
From: Jayanth Vasupilli <156448548+jayanthvee@users.noreply.github.com>
Date: Thu, 15 Oct 2026 16:30:58 -0700
Subject: [PATCH 06/12] feat(web): add the Needs help screen and the
 engine-word test

Every row that needs a person, newest first, with its plain reason and its two possible actions, Try again and Dismiss. The safety rule is PL-015's, unchanged: a row that may already have been saved keeps both buttons disabled until the person ticks 'I checked Odoo and it isn't there', and only then does the request carry destination_checked_by. A row that never reached a commit needs no tick. A 409 shows the API's own words beside the button that caused it and nothing is retried; a 503 from the operator route switches every action on the page off and says why.

apps/web/tests/engineWords.test.tsx renders every page with sample data and fails if the text a person sees contains recipe, ledger, parked, record key, verified, rung, idempotency, v1, v2, step_, fill- or click-, with each forbidden word mapped to the DESIGN.md wording it must appear as instead.
---
 apps/web/src/pages/NeedsHelp.tsx       | 188 +++++++++++++-
 apps/web/src/pages/needsHelp.css       | 106 ++++++++
 apps/web/src/pages/needsHelpActions.ts | 121 +++++++++
 apps/web/tests/engineWords.test.tsx    | 289 +++++++++++++++++++++
 apps/web/tests/needsHelp.test.tsx      | 336 +++++++++++++++++++++++++
 5 files changed, 1037 insertions(+), 3 deletions(-)
 create mode 100644 apps/web/src/pages/needsHelp.css
 create mode 100644 apps/web/src/pages/needsHelpActions.ts
 create mode 100644 apps/web/tests/engineWords.test.tsx
 create mode 100644 apps/web/tests/needsHelp.test.tsx

diff --git a/apps/web/src/pages/NeedsHelp.tsx b/apps/web/src/pages/NeedsHelp.tsx
index a2f2a03..f741cb8 100644
--- a/apps/web/src/pages/NeedsHelp.tsx
+++ b/apps/web/src/pages/NeedsHelp.tsx
@@ -1,6 +1,188 @@
-import { EmptyState } from "../shell/EmptyState";
+import { type CSSProperties, useState } from "react";
 
-/** Placeholder: builder D replaces this file with the rows that need a person. */
+import { apiPost, errorText } from "../lib/api";
+import { useJson } from "../lib/useJson";
+import { plainReason, rowOutcome } from "../lib/words";
+import type { NeedsHelpRow, OperatorInfo } from "../types";
+import {
+  DESTINATION_CHECK_LABEL,
+  DESTINATION_CHECK_WHY,
+  OPERATOR_NOTE,
+  OPERATOR_PROBLEM,
+  actionBody,
+  actionGate,
+  recordActionLabel,
+  recordActionPath,
+  type RecordAction,
+} from "./needsHelpActions";
+import "./needsHelp.css";
+
+/** The blur-in stagger for the sections (DESIGN.md §7). */
+function slot(index: number): CSSProperties {
+  return { "--i": index } as CSSProperties;
+}
+
+/**
+ * The rows that need a person: every row `GET /api/v1/needs-help` returns, newest first (the route
+ * already orders them), each with its outcome in plain words and one action -- Try again, or
+ * Dismiss.
+ *
+ * The safety rule is the ticket's requirement 6 and it is unchanged from PL-015: a row that may
+ * already have been saved (`commit_attempted`) keeps both buttons disabled until the person ticks
+ * "I checked Odoo and it isn't there", and only then does the request carry
+ * `destination_checked_by` -- the operator id from `GET /api/v1/operator`. A row that never reached
+ * a commit needs no tick and sends an empty body. The Shell already renders this page's primary
+ * action slot, so every button this page draws itself is quiet.
+ */
 export function NeedsHelp(): JSX.Element {
-  return <EmptyState sentence="The rows that need your help will appear here." />;
+  const help = useJson<NeedsHelpRow[]>("/api/v1/needs-help");
+  const operator = useJson<OperatorInfo>("/api/v1/operator");
+
+  // The ticks belong to one person's visit: nothing on this page ever ticks the box itself, and a
+  // reload leaves every box clear.
+  const [confirmed, setConfirmed] = useState<Record<string, boolean>>({});
+  const [busy, setBusy] = useState<string | null>(null);
+  const [errors, setErrors] = useState<Record<string, string>>({});
+
+  const rows = Array.isArray(help.data) ? help.data : [];
+  const operatorId = operator.data?.operator_id ?? null;
+  // A refusal from the operator route (503, or a host we could not reach) is the API's own words.
+  const operatorProblem = operator.error;
+
+  function ticket(recordId: string, checked: boolean): void {
+    setConfirmed((current) => ({ ...current, [recordId]: checked }));
+  }
+
+  async function act(row: NeedsHelpRow, action: RecordAction): Promise<void> {
+    const gate = actionGate({
+      state: row.state,
+      commitAttempted: row.commit_attempted === true,
+      confirmed: confirmed[row.record_id] === true,
+      operatorId,
+      operatorUnavailable: operatorProblem !== null,
+    });
+    if (gate.disabled || gate.shown === false || busy !== null) return;
+    setBusy(row.record_id);
+    setErrors((current) => {
+      const next = { ...current };
+      delete next[row.record_id];
+      return next;
+    });
+    try {
+      await apiPost(
+        recordActionPath(row.record_id, action),
+        actionBody({
+          commitAttempted: row.commit_attempted === true,
+          confirmed: confirmed[row.record_id] === true,
+          operatorId,
+        }),
+      );
+      help.reload();
+    } catch (failure) {
+      // The API's own `detail` text, shown beside the button that caused it. Nothing is retried.
+      setErrors((current) => ({ ...current, [row.record_id]: errorText(failure) }));
+    } finally {
+      setBusy(null);
+    }
+  }
+
+  return (
+    <div className="needs-help">
+      {operatorProblem === null ? null : (
+        <p className="operator-note in" style={slot(1)} role="status">
+          {OPERATOR_PROBLEM}
+          {": "}
+          <span className="operator-problem">{operatorProblem}</span> {OPERATOR_NOTE}
+        </p>
+      )}
+
+      <section className="panel in" style={slot(operatorProblem === null ? 1 : 2)}>
+        <div className="panel-h">
+          <h3>Needs your help</h3>
+          {rows.length === 0 ? null : <span>{rows.length} waiting</span>}
+        </div>
+        {rows.length === 0 ? (
+          <p className="panel-note">
+            {help.error ??
+              "Nothing needs you right now \u2014 the rows that need your decision will appear here."}
+          </p>
+        ) : (
+          <ul className="rows">
+            {rows.map((row) => {
+              const outcome = rowOutcome(row.state);
+              const ticked = confirmed[row.record_id] === true;
+              const gate = actionGate({
+                state: row.state,
+                commitAttempted: row.commit_attempted === true,
+                confirmed: ticked,
+                operatorId,
+                operatorUnavailable: operatorProblem !== null,
+              });
+              const refusal = errors[row.record_id];
+              const boxId = `checked-odoo-${row.record_id}`;
+              return (
+                <li key={row.record_id}>
+                  <div>
+                    {/* The row's key is the person's or thing's name for it: data, rendered as
+                        text. The reason is the one sentence that says why it needs a person. */}
+                    <b>{row.row}</b>
+                    <p>{plainReason(row.reason, row.state)}</p>
+                    <small>{row.task_name}</small>
+                  </div>
+                  <div className="row-actions">
+                    <span className={`res ${outcome.tone}`}>{outcome.label}</span>
+                    {gate.shown === false ? null : (
+                      <span className="record-buttons">
+                        <button
+                          type="button"
+                          className="btn quiet record-requeue"
+                          disabled={gate.disabled || busy !== null}
+                          onClick={() => void act(row, "requeue")}
+                        >
+                          {recordActionLabel("requeue")}
+                        </button>
+                        <button
+                          type="button"
+                          className="btn quiet record-dismiss"
+                          disabled={gate.disabled || busy !== null}
+                          onClick={() => void act(row, "dismiss")}
+                        >
+                          {recordActionLabel("dismiss")}
+                        </button>
+                      </span>
+                    )}
+                    {refusal === undefined ? null : (
+                      <span className="action-error" role="status">
+                        {refusal}
+                      </span>
+                    )}
+                  </div>
+                  {/* The destination check belongs on its own line under the whole row, not in
+                      the narrow action column: it is a sentence, and squeezing it into the
+                      right-hand slot makes the row half empty and twice as tall. */}
+                  {gate.needsConfirmation ? (
+                    <div className="destination-check">
+                      <span className="destination-check-line">
+                        <input
+                          id={boxId}
+                          className="destination-check-box"
+                          type="checkbox"
+                          checked={ticked}
+                          onChange={(event) => ticket(row.record_id, event.currentTarget.checked)}
+                        />
+                        <label className="destination-check-label" htmlFor={boxId}>
+                          {DESTINATION_CHECK_LABEL}
+                        </label>
+                      </span>
+                      <p className="destination-check-why">{DESTINATION_CHECK_WHY}</p>
+                    </div>
+                  ) : null}
+                </li>
+              );
+            })}
+          </ul>
+        )}
+      </section>
+    </div>
+  );
 }
diff --git a/apps/web/src/pages/needsHelp.css b/apps/web/src/pages/needsHelp.css
new file mode 100644
index 0000000..135f6d5
--- /dev/null
+++ b/apps/web/src/pages/needsHelp.css
@@ -0,0 +1,106 @@
+/* Needs help's own placement. Every shared primitive -- the panel, the rows, the quiet button and
+   the blur-in entrance -- is already ported into styles/global.css, so nothing here duplicates it. */
+
+.needs-help {
+  display: grid;
+  gap: 30px;
+  align-content: start;
+}
+
+/* The operator problem: the API's own words, said once above the rows. */
+.needs-help .operator-note {
+  margin: 0;
+  padding: 14px 18px;
+  border: 1px solid var(--hair-2);
+  border-radius: 12px;
+  background: var(--glass);
+  color: var(--ink-2);
+  font-size: 14px;
+}
+
+.needs-help .operator-problem {
+  color: var(--ink);
+}
+
+.needs-help .panel-note {
+  margin: 0;
+  padding: 12px 20px 20px;
+  color: var(--ink-2);
+  font-size: 14px;
+}
+
+/* One row's decision: the outcome, then the one action it offers. */
+.needs-help .row-actions {
+  display: grid;
+  gap: 8px;
+  justify-items: end;
+  align-content: center;
+}
+
+.needs-help .row-actions .res {
+  font-size: 13.5px;
+}
+
+.needs-help .record-buttons {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+  flex-wrap: wrap;
+  justify-content: flex-end;
+}
+
+/* The reason the box exists, in one sentence, beside the box. It spans the whole row, under the
+   row's own line: a sentence in the narrow action column would leave the row half empty and twice
+   as tall. */
+.needs-help .rows li { align-items: center; }
+
+.needs-help .destination-check {
+  grid-column: 1 / -1;
+  display: grid;
+  gap: 4px;
+  justify-items: start;
+  margin-top: 10px;
+  padding-top: 10px;
+  border-top: 1px solid var(--hair);
+}
+
+.needs-help .destination-check-line {
+  display: inline-flex;
+  gap: 7px;
+  align-items: center;
+  color: var(--ink);
+  font-size: 13.5px;
+  cursor: pointer;
+}
+
+.needs-help .destination-check-why {
+  margin: 0;
+  color: var(--muted);
+  font-size: 13px;
+  max-width: 62ch;
+}
+
+/* A refusal sits beside the button that caused it, in the API's own words. */
+.needs-help .action-error {
+  color: var(--help);
+  font-size: 13px;
+  max-width: 320px;
+  text-align: right;
+}
+
+.needs-help .rows small {
+  color: var(--muted);
+  font-size: 13px;
+}
+
+@media (max-width: 780px) {
+  .needs-help .row-actions,
+  .needs-help .action-error {
+    justify-items: start;
+    text-align: left;
+  }
+
+  .needs-help .record-buttons {
+    justify-content: flex-start;
+  }
+}
diff --git a/apps/web/src/pages/needsHelpActions.ts b/apps/web/src/pages/needsHelpActions.ts
new file mode 100644
index 0000000..36c4ab5
--- /dev/null
+++ b/apps/web/src/pages/needsHelpActions.ts
@@ -0,0 +1,121 @@
+/**
+ * The pure decisions the Needs help page makes: when the safety gate lets an action through, what
+ * the request body carries, and the two endpoint paths.
+ *
+ * This is the same shape PL-015's `src/logic.ts` had, so `needsHelp.test.tsx` can call these
+ * functions directly as well as through the page. A commit-attempted row may already have been
+ * saved, so the gate is the one place a person can get past the ledger's duplicate protection and
+ * it is never one click (ticket PL-023 requirement 6; the safety rule is unchanged from PL-015).
+ */
+
+import type { RecordActionBody } from "../types";
+
+/** The exact words the confirmation carries. The ticket fixes them. */
+export const DESTINATION_CHECK_LABEL = "I checked Odoo and it isn't there";
+
+/** Why the box is there, in one sentence, next to it. */
+export const DESTINATION_CHECK_WHY =
+  "We may already have saved this row before it went wrong, so look it up in Odoo and tick the box only if it is not there.";
+
+/**
+ * Said once at the top of the page when `GET /api/v1/operator` refuses. The API's own `detail` text
+ * follows it verbatim, so the person can see the words the server used.
+ */
+export const OPERATOR_PROBLEM =
+  "The API has no operator identity, so every action on this page is off";
+
+/** What to do about it, keeping the API's own variable name in view. */
+export const OPERATOR_NOTE =
+  "Set PROCESSLENS_OPERATOR_ID and restart the API, then reload this page.";
+
+export type RecordAction = "requeue" | "dismiss";
+
+/** The words on the button that asks for one action. */
+export function recordActionLabel(action: RecordAction): string {
+  return action === "requeue" ? "Try again" : "Dismiss";
+}
+
+/** The path the API already serves, built from the record the row carries. */
+export function recordActionPath(recordId: string, action: RecordAction): string {
+  return `/api/v1/records/${encodeURIComponent(recordId)}/${action}`;
+}
+
+export interface RecordActions {
+  requeue: boolean;
+  dismiss: boolean;
+}
+
+/** Try again and Dismiss appear for the rows this page lists: the ones that need a person. */
+export function recordActions(state: string): RecordActions {
+  const actionable = state === "parked" || state === "failed";
+  return { requeue: actionable, dismiss: actionable };
+}
+
+export interface ActionGateInput {
+  state: string;
+  commitAttempted: boolean;
+  confirmed: boolean;
+  operatorId: string | null;
+  /** True when `GET /api/v1/operator` refused: the page has nobody to record, so nothing may act. */
+  operatorUnavailable?: boolean;
+}
+
+export interface ActionGate {
+  /** Whether this row offers an action at all. */
+  shown: boolean;
+  /** A commit-attempted row needs the destination check ticked first. */
+  needsConfirmation: boolean;
+  /** Only the checked-destination path has to send the operator id. */
+  needsOperator: boolean;
+  disabled: boolean;
+}
+
+/**
+ * The one place the page can get past the ledger's duplicate protection, so it is never one click.
+ * A commit-attempted row keeps both buttons disabled until the confirmation is ticked, clearing the
+ * tick disables them again, and a page with no operator identity disables every action on it.
+ */
+export function actionGate(input: ActionGateInput): ActionGate {
+  const actions = recordActions(input.state);
+  if (actions.requeue === false) {
+    return { shown: false, needsConfirmation: false, needsOperator: false, disabled: true };
+  }
+  const needsConfirmation = input.commitAttempted === true;
+  const needsOperator = needsConfirmation;
+  const confirmationMissing = needsConfirmation && input.confirmed !== true;
+  const operatorMissing = input.operatorId === null || input.operatorId === "";
+  return {
+    shown: true,
+    needsConfirmation,
+    needsOperator,
+    disabled:
+      input.operatorUnavailable === true || confirmationMissing || (needsOperator && operatorMissing),
+  };
+}
+
+export interface ActionBodyInput {
+  commitAttempted: boolean;
+  confirmed: boolean;
+  operatorId: string | null;
+  reason?: string | null;
+}
+
+/**
+ * The exact body the record endpoints get. `destination_checked_by` is sent only after the check
+ * has been confirmed, and the id is never invented; a row that never reached a commit sends `{}`.
+ */
+export function actionBody(input: ActionBodyInput): RecordActionBody {
+  const body: RecordActionBody = {};
+  const reason = input.reason === undefined || input.reason === null ? "" : input.reason.trim();
+  if (reason !== "") body.reason = reason;
+  if (input.commitAttempted === true) {
+    if (input.confirmed !== true) {
+      throw new Error("A commit-attempted row needs the destination check confirmed first.");
+    }
+    if (input.operatorId === null || input.operatorId === "") {
+      throw new Error("A commit-attempted row needs the API's operator identity.");
+    }
+    body.destination_checked_by = input.operatorId;
+  }
+  return body;
+}
diff --git a/apps/web/tests/engineWords.test.tsx b/apps/web/tests/engineWords.test.tsx
new file mode 100644
index 0000000..267c107
--- /dev/null
+++ b/apps/web/tests/engineWords.test.tsx
@@ -0,0 +1,289 @@
+/**
+ * Requirement 7: no engine word ever reaches a person's eyes.
+ *
+ * Every page is rendered with sample data, the visible text of the rendered tree is collected, and
+ * the test fails if it contains any of the forbidden words below -- case-insensitively, on the text
+ * a person sees (never on an attribute value). Each forbidden word maps to the plain wording
+ * DESIGN.md §2 requires instead:
+ *
+ *   recipe       -> "task"
+ *   ledger       -> never shown (the ledger is not a thing a person has)
+ *   parked       -> "needs your help"
+ *   record key   -> "row", or the person's or thing's name ("Priya Nair")
+ *   verified     -> "added", "updated" or "done" (the task's verb)
+ *   rung         -> never shown (a step's target ladder is internal)
+ *   idempotency  -> never shown
+ *   v1, v2       -> never shown (a task's history says "Changed on 14 Oct")
+ *   step_        -> never shown (a step is one sentence: "Click Save")
+ *   fill-, click- -> never shown (the element's own words, not its code)
+ *
+ * The sample data is plain too: a fixture may not carry a forbidden word, or the test would only be
+ * testing itself. The identifiers the API sends *as* engine words (`state: "parked"`, the keys of
+ * `counts`) are excluded from that check on purpose -- every page maps them through `lib/words.ts`
+ * before they can be rendered, which is exactly what the page checks below prove.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import type {
+  HomeSummary,
+  NeedsHelpRow,
+  RecordRow,
+  RunDetail as RunDetailPayload,
+  RunSummary,
+  TaskRow,
+} from "../src/types";
+import { createFetchStub, renderApp, settle, type StubRoutes } from "./helpers";
+
+const OPERATOR_ID = "0f8fad5b-d9cb-469f-a165-70867728950e";
+
+interface Forbidden {
+  engine: string;
+  pattern: RegExp;
+  plain: string;
+}
+
+const FORBIDDEN: Forbidden[] = [
+  { engine: "recipe", pattern: /recipe/i, plain: "task" },
+  { engine: "ledger", pattern: /ledger/i, plain: "never shown" },
+  { engine: "parked", pattern: /parked/i, plain: "needs your help" },
+  { engine: "record key", pattern: /record[\s_-]*key/i, plain: "the person's or thing's name" },
+  { engine: "verified", pattern: /verified/i, plain: "added, updated or done" },
+  { engine: "rung", pattern: /rung/i, plain: "never shown" },
+  { engine: "idempotency", pattern: /idempotency/i, plain: "never shown" },
+  // Whole tokens only, so an ordinary word or an id that merely contains the letters is not a hit.
+  { engine: "v1", pattern: /\bv1\b/i, plain: "never shown" },
+  { engine: "v2", pattern: /\bv2\b/i, plain: "never shown" },
+  { engine: "step_", pattern: /step_/i, plain: "one plain sentence" },
+  { engine: "fill-", pattern: /fill-/i, plain: "the element's own words" },
+  { engine: "click-", pattern: /click-/i, plain: "the element's own words" },
+];
+
+/** Every forbidden word this text contains, so a failure names the rule it broke. */
+function engineWordsIn(text: string): string[] {
+  return FORBIDDEN.filter((rule) => rule.pattern.test(text)).map((rule) => rule.engine);
+}
+
+/* ------------------------------------------------------------------ */
+/* Sample data, written in the words a person would use                */
+/* ------------------------------------------------------------------ */
+
+const TASK: TaskRow = {
+  workflow_id: "task-1",
+  recipe_version_id: "version-1",
+  name: "Add inquiries",
+  app: "crm.example.com",
+  last_run: {
+    run_id: "run-1",
+    status: "completed",
+    started_at: "2026-10-15T09:00:00Z",
+    counts: { verified: 4, skipped: 1, parked: 1 },
+  },
+};
+
+const RUN_SUMMARY: RunSummary = {
+  id: "run-1",
+  status: "completed",
+  pause_reason: null,
+  created_at: "2026-10-15T09:00:00Z",
+  recipe_name: "Add inquiries",
+  recipe_version: "version-1",
+  counts: { verified: 4, skipped: 1, parked: 1 },
+};
+
+const RUN_DETAIL: RunDetailPayload = {
+  id: "run-1",
+  status: "completed",
+  pause_reason: null,
+  counts: { total: 6, verified: 4, skipped: 1, parked: 1, failed: 0 },
+  open_approval: null,
+  started_at: "2026-10-15T09:00:00Z",
+  finished_at: "2026-10-15T09:15:00Z",
+};
+
+const RUN_ROWS: RecordRow[] = [
+  {
+    id: "row-a",
+    record_key: "Priya Nair",
+    state: "verified",
+    reason: null,
+    attempts: 1,
+    max_attempts: 3,
+    commit_attempted: true,
+    destination_ref: "crm.example.com/leads/9",
+  },
+  {
+    id: "row-b",
+    record_key: "ACME-1",
+    state: "skipped",
+    reason: "duplicate",
+    attempts: 1,
+    max_attempts: 3,
+    commit_attempted: false,
+    destination_ref: null,
+  },
+  {
+    id: "row-c",
+    record_key: "ACME-2",
+    state: "parked",
+    reason: "missing email",
+    attempts: 2,
+    max_attempts: 3,
+    commit_attempted: true,
+    destination_ref: null,
+  },
+];
+
+const HELP_ROWS: NeedsHelpRow[] = [
+  {
+    record_id: "row-c",
+    run_id: "run-1",
+    task_name: "Add inquiries",
+    row: "ACME-2",
+    state: "parked",
+    reason: "missing email",
+    commit_attempted: true,
+  },
+];
+
+const HOME: HomeSummary = {
+  window_days: 7,
+  counts: { done: 4, already_there: 1, needs_help: 1 },
+  minutes_saved: 34,
+  needs_help: HELP_ROWS,
+  running: [{ run_id: "run-2", task_name: "Add inquiries", done: 11, total: 20, already_there: 2 }],
+  tasks: [TASK],
+};
+
+/** The stored task's document, as `GET /api/v1/recipes/{id}` answers it (builder C reads it). */
+const RECIPE = {
+  id: "version-1",
+  workflow_id: "task-1",
+  workflow_name: "Add inquiries",
+  version: 2,
+  name: "Add inquiries",
+  recipe: {
+    steps: [
+      { action: "navigate", url: "https://crm.example.com/leads" },
+      { action: "fill", targets: [{ by: "label", text: "Email" }], value: "{{row.email}}" },
+      { action: "click", targets: [{ by: "role", name: "Save" }] },
+      { action: "end_record" },
+    ],
+  },
+};
+
+function routes(extra: StubRoutes = {}): StubRoutes {
+  return {
+    "/api/v1/home": { body: HOME },
+    "/api/v1/needs-help": { body: HELP_ROWS },
+    "/api/v1/operator": { body: { operator_id: OPERATOR_ID } },
+    "/api/v1/executor/session": { body: { attached: true } },
+    "/api/v1/tasks": { body: [TASK] },
+    "/api/v1/runs/run-1/records": { body: RUN_ROWS },
+    "/api/v1/runs/run-1": { body: RUN_DETAIL },
+    "/api/v1/runs": { body: [RUN_SUMMARY] },
+    "/api/v1/recipes/version-1": { body: RECIPE },
+    ...extra,
+  };
+}
+
+/** The text a person sees: the rendered tree's text, never an attribute value. */
+function visibleText(container: HTMLElement): string {
+  return container.textContent ?? "";
+}
+
+async function textOf(path: string): Promise<string> {
+  const stub = createFetchStub(routes());
+  const view = renderApp(path);
+  await settle();
+  const text = visibleText(view.container);
+  stub.restore();
+  view.unmount();
+  return text;
+}
+
+const PAGES: { name: string; path: string; shows: string[] }[] = [
+  { name: "Home", path: "/", shows: ["rows done this week.", "Add inquiries"] },
+  { name: "Needs help", path: "/needs-help", shows: ["ACME-2", "Missing email."] },
+  { name: "Tasks", path: "/tasks", shows: ["Add inquiries", "crm.example.com"] },
+  { name: "Task detail", path: "/tasks/task-1", shows: ["Add inquiries", "Type the email"] },
+  { name: "Runs", path: "/runs", shows: ["Add inquiries"] },
+  { name: "Run detail", path: "/runs/run-1", shows: ["Priya Nair", "ACME-2"] },
+  { name: "ComingSoon", path: "/teach", shows: ["Teaching a new task"] },
+];
+
+/* ------------------------------------------------------------------ */
+
+describe("the checker itself", () => {
+  it("catches an engine word and leaves ordinary words alone", () => {
+    expect(engineWordsIn("This recipe was verified and then parked")).toEqual([
+      "recipe",
+      "parked",
+      "verified",
+    ]);
+    expect(engineWordsIn("The row key: Priya Nair")).toEqual([]);
+    expect(engineWordsIn("row-rv-1 and row-v12 are ids, not words")).toEqual([]);
+    expect(engineWordsIn("It was added twice")).toEqual([]);
+  });
+});
+
+describe("every page shows only plain words", () => {
+  for (const page of PAGES) {
+    it(`${page.name} shows none of the forbidden words`, async () => {
+      const text = await textOf(page.path);
+      expect(text.trim()).not.toBe("");
+      // The page really rendered its sample data, so a blank screen can never pass this. 
+      for (const expected of page.shows) {
+        expect(text, `${page.name} should show "${expected}"`).toContain(expected);
+      }
+      const found = engineWordsIn(text);
+      // The message names each word and the DESIGN.md §2 wording it must appear as instead.
+      const detail = found
+        .map((engine) => `${engine} (show "${FORBIDDEN.find((r) => r.engine === engine)?.plain}")`)
+        .join(", ");
+      expect(found, `${page.name} must say: ${detail}`).toEqual([]);
+    });
+  }
+});
+
+describe("the sample data", () => {
+  it("carries no forbidden word in anything a page shows", () => {
+    // An engine state or a count name is an identifier the API sends, and every page maps it
+    // through lib/words.ts; those keys are not shown, so they are skipped here.
+    const notShown = new Set([
+      "state",
+      "status",
+      "counts",
+      "pause_reason",
+      "id",
+      "run_id",
+      "record_id",
+      "row_id",
+      "workflow_id",
+      "recipe_version_id",
+      "recipe_version",
+    ]);
+    const shown: string[] = [];
+    const walk = (value: unknown, key: string): void => {
+      if (notShown.has(key)) return;
+      if (typeof value === "string") {
+        shown.push(value);
+        return;
+      }
+      if (Array.isArray(value)) {
+        for (const entry of value) walk(entry, key);
+        return;
+      }
+      if (value !== null && typeof value === "object") {
+        for (const [name, entry] of Object.entries(value as Record<string, unknown>)) {
+          walk(entry, name);
+        }
+      }
+    };
+    walk({ HOME, TASK, RUN_SUMMARY, RUN_DETAIL, RUN_ROWS, HELP_ROWS, RECIPE }, "root");
+
+    for (const value of shown) {
+      expect(engineWordsIn(value), `the sample data says "${value}"`).toEqual([]);
+    }
+  });
+});
diff --git a/apps/web/tests/needsHelp.test.tsx b/apps/web/tests/needsHelp.test.tsx
new file mode 100644
index 0000000..f93e49e
--- /dev/null
+++ b/apps/web/tests/needsHelp.test.tsx
@@ -0,0 +1,336 @@
+/**
+ * Needs help: the safety gate, the request body, the endpoints, the operator's 503 and a 409's own
+ * words beside the button that caused it.
+ *
+ * These are PL-015's `commitGate.test.ts` and the operator half of `errorDetail.test.ts` carried
+ * forward as React tests: requirement 6 of PL-023 says the safety rule is unchanged and mandatory,
+ * so the same assertions hold here. The pure decisions live in `needsHelpActions.ts` and are called
+ * directly as well as through the page.
+ */
+
+import { fireEvent } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import {
+  DESTINATION_CHECK_LABEL,
+  OPERATOR_PROBLEM,
+  actionBody,
+  actionGate,
+  recordActionPath,
+  recordActions,
+} from "../src/pages/needsHelpActions";
+import type { NeedsHelpRow } from "../src/types";
+import {
+  callsTo,
+  createFetchStub,
+  renderApp,
+  settle,
+  type StubRoutes,
+} from "./helpers";
+
+const OPERATOR_ID = "0f8fad5b-d9cb-469f-a165-70867728950e";
+
+/** The API's own words for a missing operator identity (services/api/main.py). */
+const OPERATOR_503 = "PROCESSLENS_OPERATOR_ID is not set, so there is no operator id to act as";
+/** The API's own words when the ledger will not make the move (services/api/runs.py). */
+const CONFLICT = "record record-1 is parked and commit_attempted needs a destination check";
+
+function sampleRow(over: Partial<NeedsHelpRow> = {}): NeedsHelpRow {
+  return {
+    record_id: "record-1",
+    run_id: "run-1",
+    task_name: "Add inquiries",
+    row: "ACME-1",
+    state: "parked",
+    reason: "missing email",
+    commit_attempted: true,
+    ...over,
+  };
+}
+
+function routes(rows: NeedsHelpRow[], extra: StubRoutes = {}): StubRoutes {
+  return {
+    "/api/v1/needs-help": { body: rows },
+    "/api/v1/operator": { body: { operator_id: OPERATOR_ID } },
+    "/api/v1/executor/session": { body: { attached: true } },
+    ...extra,
+  };
+}
+
+function button(container: HTMLElement, selector: string): HTMLButtonElement {
+  const node = container.querySelector<HTMLButtonElement>(selector);
+  if (node === null) throw new Error(`no button matching ${selector}`);
+  return node;
+}
+
+function checkbox(container: HTMLElement): HTMLInputElement {
+  const node = container.querySelector<HTMLInputElement>(".destination-check-box");
+  if (node === null) throw new Error("no destination-check checkbox");
+  return node;
+}
+
+function posts(stub: { requests: { method: string; path: string; body: unknown }[] }, path: string) {
+  return stub.requests.filter((call) => call.method === "POST" && call.path === path);
+}
+
+describe("the gate itself", () => {
+  it("names both requirements and no more", () => {
+    const gate = actionGate({
+      state: "parked",
+      commitAttempted: true,
+      confirmed: false,
+      operatorId: OPERATOR_ID,
+    });
+    expect(gate.needsConfirmation).toBe(true);
+    expect(gate.needsOperator).toBe(true);
+    expect(gate.disabled).toBe(true);
+    expect(gate.shown).toBe(true);
+  });
+
+  it("leaves a row that does not need a person alone", () => {
+    const gate = actionGate({
+      state: "verified",
+      commitAttempted: true,
+      confirmed: true,
+      operatorId: OPERATOR_ID,
+    });
+    expect(gate.shown).toBe(false);
+    expect(recordActions("verified")).toEqual({ requeue: false, dismiss: false });
+  });
+
+  it("stays disabled while the API has no operator id to send", () => {
+    const gate = actionGate({
+      state: "parked",
+      commitAttempted: true,
+      confirmed: true,
+      operatorId: null,
+    });
+    expect(gate.disabled).toBe(true);
+  });
+
+  it("asks nothing extra of a row that never reached a commit", () => {
+    const gate = actionGate({
+      state: "failed",
+      commitAttempted: false,
+      confirmed: false,
+      operatorId: null,
+    });
+    expect(gate.needsConfirmation).toBe(false);
+    expect(gate.needsOperator).toBe(false);
+    expect(gate.disabled).toBe(false);
+  });
+
+  it("disables every action when the operator endpoint refused", () => {
+    const gate = actionGate({
+      state: "failed",
+      commitAttempted: false,
+      confirmed: false,
+      operatorId: null,
+      operatorUnavailable: true,
+    });
+    expect(gate.disabled).toBe(true);
+    // The id is not what a plain row needs; the page simply has nobody to record.
+    expect(gate.needsOperator).toBe(false);
+  });
+});
+
+describe("the request body", () => {
+  it("carries the operator id only when a commit was attempted and the check was confirmed", () => {
+    expect(
+      actionBody({ commitAttempted: false, confirmed: false, operatorId: OPERATOR_ID }),
+    ).toEqual({});
+    expect(
+      actionBody({ commitAttempted: true, confirmed: true, operatorId: OPERATOR_ID }),
+    ).toEqual({ destination_checked_by: OPERATOR_ID });
+    expect(() =>
+      actionBody({ commitAttempted: true, confirmed: false, operatorId: OPERATOR_ID }),
+    ).toThrow();
+    expect(() =>
+      actionBody({ commitAttempted: true, confirmed: true, operatorId: null }),
+    ).toThrow();
+  });
+});
+
+describe("the endpoints", () => {
+  it("builds the two paths the API already serves", () => {
+    expect(recordActionPath("record-1", "requeue")).toBe("/api/v1/records/record-1/requeue");
+    expect(recordActionPath("record-1", "dismiss")).toBe("/api/v1/records/record-1/dismiss");
+    expect(recordActionPath("a b/c", "dismiss")).toBe("/api/v1/records/a%20b%2Fc/dismiss");
+  });
+});
+
+describe("the destination check gates a commit-attempted row on the page", () => {
+  it("disables both buttons until the unticked box is ticked, and again once it is cleared", async () => {
+    const stub = createFetchStub(routes([sampleRow()]));
+    const view = renderApp("/needs-help");
+    await settle();
+
+    const box = checkbox(view.container);
+    expect(box.checked).toBe(false);
+    expect(view.container.querySelector(".destination-check-label")?.textContent).toBe(
+      DESTINATION_CHECK_LABEL,
+    );
+    // The reason for the box is next to it, in one sentence.
+    expect(
+      view.container.querySelector(".destination-check-why")?.textContent?.trim(),
+    ).not.toBe("");
+    expect(button(view.container, ".record-requeue").disabled).toBe(true);
+    expect(button(view.container, ".record-dismiss").disabled).toBe(true);
+
+    fireEvent.click(box);
+    await settle();
+    expect(checkbox(view.container).checked).toBe(true);
+    expect(button(view.container, ".record-requeue").disabled).toBe(false);
+    expect(button(view.container, ".record-dismiss").disabled).toBe(false);
+
+    fireEvent.click(checkbox(view.container));
+    await settle();
+    expect(button(view.container, ".record-requeue").disabled).toBe(true);
+    expect(button(view.container, ".record-dismiss").disabled).toBe(true);
+    stub.restore();
+    view.unmount();
+  });
+
+  it("asks nothing extra of a row that never reached a commit", async () => {
+    const stub = createFetchStub(
+      routes([sampleRow({ state: "failed", commit_attempted: false })], {
+        "/api/v1/records/record-1/dismiss": { body: { record_id: "record-1", state: "skipped" } },
+      }),
+    );
+    const view = renderApp("/needs-help");
+    await settle();
+
+    expect(view.container.querySelector(".destination-check-box")).toBeNull();
+    const dismiss = button(view.container, ".record-dismiss");
+    expect(dismiss.disabled).toBe(false);
+    fireEvent.click(dismiss);
+    await settle();
+
+    const sent = posts(stub, "/api/v1/records/record-1/dismiss");
+    expect(sent).toHaveLength(1);
+    expect(sent[0]?.body).toEqual({});
+    stub.restore();
+    view.unmount();
+  });
+
+  it("sends destination_checked_by only after the tick, and ticks nothing by itself", async () => {
+    const stub = createFetchStub(
+      routes([sampleRow()], {
+        "/api/v1/records/record-1/dismiss": { body: { record_id: "record-1", state: "skipped" } },
+      }),
+    );
+    const view = renderApp("/needs-help");
+    await settle();
+
+    // Nothing is ticked on the page's own account.
+    expect(checkbox(view.container).checked).toBe(false);
+    fireEvent.click(button(view.container, ".record-dismiss"));
+    await settle();
+    expect(posts(stub, "/api/v1/records/record-1/dismiss")).toHaveLength(0);
+
+    fireEvent.click(checkbox(view.container));
+    await settle();
+    expect(button(view.container, ".record-dismiss").disabled).toBe(false);
+    fireEvent.click(button(view.container, ".record-dismiss"));
+    await settle();
+
+    const sent = posts(stub, "/api/v1/records/record-1/dismiss");
+    expect(sent).toHaveLength(1);
+    expect(sent[0]?.body).toEqual({ destination_checked_by: OPERATOR_ID });
+    stub.restore();
+    view.unmount();
+  });
+});
+
+describe("a refused request shows the API's detail text next to the button", () => {
+  it("shows a 409 from Dismiss beside the Dismiss button and does not retry", async () => {
+    const stub = createFetchStub(
+      routes([sampleRow({ commit_attempted: false })], {
+        "/api/v1/records/record-1/dismiss": { status: 409, body: { detail: CONFLICT } },
+      }),
+    );
+    const view = renderApp("/needs-help");
+    await settle();
+
+    fireEvent.click(button(view.container, ".record-dismiss"));
+    await settle();
+
+    const cell = view.container.querySelector<HTMLElement>(".row-actions");
+    const error = cell?.querySelector<HTMLElement>(".action-error");
+    expect(error?.textContent).toBe(CONFLICT);
+    // "next to the button": the same cell the Dismiss button lives in.
+    expect(button(view.container, ".record-dismiss").closest(".row-actions")).toBe(cell);
+
+    expect(callsTo(stub, "/api/v1/records/record-1/dismiss")).toBe(1);
+    await settle();
+    expect(callsTo(stub, "/api/v1/records/record-1/dismiss")).toBe(1);
+    stub.restore();
+    view.unmount();
+  });
+
+  it("shows a 409 from Try again beside the Try again button", async () => {
+    const stub = createFetchStub(
+      routes([sampleRow({ commit_attempted: false })], {
+        "/api/v1/records/record-1/requeue": { status: 409, body: { detail: CONFLICT } },
+      }),
+    );
+    const view = renderApp("/needs-help");
+    await settle();
+
+    fireEvent.click(button(view.container, ".record-requeue"));
+    await settle();
+
+    const cell = view.container.querySelector<HTMLElement>(".row-actions");
+    expect(cell?.querySelector(".action-error")?.textContent).toBe(CONFLICT);
+    expect(button(view.container, ".record-requeue").closest(".row-actions")).toBe(cell);
+    stub.restore();
+    view.unmount();
+  });
+});
+
+describe("the operator identity", () => {
+  it("disables every action and says why when the endpoint answers 503", async () => {
+    const stub = createFetchStub(
+      routes(
+        [sampleRow(), sampleRow({ record_id: "record-2", state: "failed", commit_attempted: false })],
+        { "/api/v1/operator": { status: 503, body: { detail: OPERATOR_503 } } },
+      ),
+    );
+    const view = renderApp("/needs-help");
+    await settle();
+
+    const buttons = view.container.querySelectorAll<HTMLButtonElement>(".record-buttons button");
+    expect(buttons.length).toBe(4);
+    for (const node of Array.from(buttons)) {
+      expect(node.disabled).toBe(true);
+    }
+    // It refuses to act, and it says why -- including the API's own words and the variable to set.
+    const note = view.container.querySelector<HTMLElement>(".operator-note");
+    expect(note?.textContent).toContain(OPERATOR_PROBLEM);
+    expect(note?.textContent).toContain("PROCESSLENS_OPERATOR_ID");
+    expect(view.container.querySelector<HTMLElement>(".operator-problem")?.textContent).toBe(
+      OPERATOR_503,
+    );
+
+    fireEvent.click(button(view.container, ".record-dismiss"));
+    await settle();
+    expect(posts(stub, "/api/v1/records/record-2/dismiss")).toHaveLength(0);
+    stub.restore();
+    view.unmount();
+  });
+});
+
+describe("the page with nothing to show", () => {
+  it("says what will appear here in one sentence and offers no primary button", async () => {
+    const stub = createFetchStub(routes([]));
+    const view = renderApp("/needs-help");
+    await settle();
+
+    const note = view.container.querySelector<HTMLElement>(".needs-help .panel-note");
+    expect(note?.textContent).toContain("Nothing needs you right now");
+    expect(view.container.querySelector(".btn.primary")).toBeNull();
+    expect(view.container.querySelector(".destination-check-box")).toBeNull();
+    stub.restore();
+    view.unmount();
+  });
+});

From 31e3e78b1f95db38c85aaa9a0f59deeb864e9888 Mon Sep 17 00:00:00 2001
From: Jayanth Vasupilli <156448548+jayanthvee@users.noreply.github.com>
Date: Thu, 15 Oct 2026 16:30:59 -0700
Subject: [PATCH 07/12] fix(web): keep every page inside a 400-pixel screen

Measured in a browser at 400 and 360 pixels: the task, run and home tables pushed the document wider than the screen. The cells lose half their side padding, a long value breaks rather than widening the page, and the column that is only context -- when a task last ran, when a run started -- is the one that hides on a phone, so the result itself always stays visible. A needs-your-help row now puts the destination check on its own line under the row instead of squeezing that sentence into the narrow action column, which had left the row half empty and twice as tall.
---
 apps/web/src/pages/Home.tsx    |  9 ++++++---
 apps/web/src/pages/Runs.tsx    |  2 +-
 apps/web/src/pages/Tasks.tsx   |  2 +-
 apps/web/src/pages/home.css    |  6 ++++++
 apps/web/src/styles/global.css | 11 ++++++++++-
 5 files changed, 24 insertions(+), 6 deletions(-)

diff --git a/apps/web/src/pages/Home.tsx b/apps/web/src/pages/Home.tsx
index 67e4a68..eda52e5 100644
--- a/apps/web/src/pages/Home.tsx
+++ b/apps/web/src/pages/Home.tsx
@@ -2,7 +2,7 @@ import { type CSSProperties, useEffect, useState } from "react";
 import { Link } from "react-router-dom";
 
 import { useJson } from "../lib/useJson";
-import { durationWords, isOpenStatus, relativeTime, runStatusWords } from "../lib/words";
+import { durationWords, isOpenStatus, plainReason, relativeTime, runStatusWords } from "../lib/words";
 import type { HomeSummary, TaskRow } from "../types";
 import "./home.css";
 
@@ -120,8 +120,11 @@ export function Home(): JSX.Element {
               {needsHelp.map((row) => (
                 <li key={row.record_id}>
                   <div>
+                    {/* The mock's row shape: what it is, why it needs a person, then what it came
+                        from. The reason is the one sentence that tells the person what to do. */}
                     <b>{row.row}</b>
-                    <p>{row.task_name}</p>
+                    <p>{plainReason(row.reason, row.state)}</p>
+                    <small>{row.task_name}</small>
                   </div>
                   <Link className="btn quiet" to="/needs-help">
                     Open
@@ -174,7 +177,7 @@ export function Home(): JSX.Element {
         {tasks.length === 0 ? (
           <p className="panel-note">No tasks yet.</p>
         ) : (
-          <table>
+          <table className="drop-second">
             <thead>
               <tr>
                 <th>Task</th>
diff --git a/apps/web/src/pages/Runs.tsx b/apps/web/src/pages/Runs.tsx
index f368ae8..4d3b940 100644
--- a/apps/web/src/pages/Runs.tsx
+++ b/apps/web/src/pages/Runs.tsx
@@ -76,7 +76,7 @@ export function Runs(): JSX.Element {
             </span>
           ) : null}
         </div>
-        <table>
+        <table className="drop-second">
           <thead>
             <tr>
               <th>Task</th>
diff --git a/apps/web/src/pages/Tasks.tsx b/apps/web/src/pages/Tasks.tsx
index bfef63b..4c1f78d 100644
--- a/apps/web/src/pages/Tasks.tsx
+++ b/apps/web/src/pages/Tasks.tsx
@@ -82,7 +82,7 @@ export function Tasks(): JSX.Element {
           <h3>Your tasks</h3>
           <span className="count">{rows.length} saved</span>
         </div>
-        <table>
+        <table className="drop-second">
           <thead>
             <tr>
               <th>Task</th>
diff --git a/apps/web/src/pages/home.css b/apps/web/src/pages/home.css
index e59990c..001f5c4 100644
--- a/apps/web/src/pages/home.css
+++ b/apps/web/src/pages/home.css
@@ -27,6 +27,12 @@
   margin: 14px 0 0;
 }
 
+/* The third line of a needs-your-help row is the task it came from: quieter than the reason. */
+.home .rows small {
+  color: var(--muted);
+  font-size: 13px;
+}
+
 @media (max-width: 780px) {
   .home .saved-fig {
     min-width: 0;
diff --git a/apps/web/src/styles/global.css b/apps/web/src/styles/global.css
index d0b9a75..d693034 100644
--- a/apps/web/src/styles/global.css
+++ b/apps/web/src/styles/global.css
@@ -82,6 +82,15 @@ td.act { text-align: right; width: 1%; white-space: nowrap; }
 
 @media (max-width: 1040px) { .two { grid-template-columns: minmax(0,1fr); } }
 @media (max-width: 780px) {
-  th:nth-child(2), td:nth-child(2) { display: none; }
+  /* Phone width: a table must not push the page sideways. The cells lose half their side padding,
+     and a long value -- a host name, an email address, a task name -- breaks rather than widening
+     the document past the screen. The status words are left alone: a state reads "Stopped", never
+     "Stopp/ed", so only the value cells may break mid-token. */
+  th, td { padding: 12px 12px; }
+  th, td b, td small { overflow-wrap: anywhere; }
+  .res { overflow-wrap: normal; }
+  /* A second column that is only context -- when a task last ran, when a run started -- is what
+     goes first on a phone. A table whose second column carries the result itself keeps it. */
+  .drop-second th:nth-child(2), .drop-second td:nth-child(2) { display: none; }
   .saved-fig { text-align: left; }
 }

From 1788e7b06db9b77775ff7550177679f21b869d69 Mon Sep 17 00:00:00 2001
From: Jayanth Vasupilli <156448548+jayanthvee@users.noreply.github.com>
Date: Thu, 15 Oct 2026 16:49:53 -0700
Subject: [PATCH 08/12] fix(web): keep the engine's own words off the screen in
 a refusal

An independent review found the leak and reproduced it with this branch's own tests: a 409 carries the ledger's raw exception text ('run_record <id> is not parked', or the database trigger's 'was commit-attempted; parked -> skipped requires a fresh destination check'), and both the Needs help page and the run page printed it verbatim. The person read a state name, a table row and an id.

lib/words.ts now owns the translation in one place. A refusal whose shape says the row was already dealt with becomes one sentence about that; anything else the API sends is measured against the same forbidden-word list the test enforces, so a sentence still carrying an engine word is replaced rather than shown. The engine-word test renders both pages in their refusal state and fails on the same rule, and the two tests that asserted the raw text now assert that the raw text never reaches the person.

The run page also gets PL-015's approval decision back, which the rebuild had dropped: the request's values in plain words (never the step id, the action name or the target ladder), one primary button and one quiet one, the operator id in the body, and both disabled with the API's own words when the operator route answers 503.
---
 apps/web/src/lib/approvals.ts          |  90 +++++++++++
 apps/web/src/lib/words.ts              |  78 +++++++++
 apps/web/src/pages/NeedsHelp.tsx       |  14 +-
 apps/web/src/pages/RunDetail.tsx       | 134 +++++++++++++---
 apps/web/src/pages/needsHelpActions.ts |  15 +-
 apps/web/src/pages/runs.css            |  72 +++++++++
 apps/web/tests/engineWords.test.tsx    |  89 ++++++++---
 apps/web/tests/needsHelp.test.tsx      |  40 +++--
 apps/web/tests/runs.test.tsx           | 212 ++++++++++++++++++++++++-
 9 files changed, 674 insertions(+), 70 deletions(-)
 create mode 100644 apps/web/src/lib/approvals.ts

diff --git a/apps/web/src/lib/approvals.ts b/apps/web/src/lib/approvals.ts
new file mode 100644
index 0000000..bef1260
--- /dev/null
+++ b/apps/web/src/lib/approvals.ts
@@ -0,0 +1,90 @@
+/**
+ * The approval decision, in plain words.
+ *
+ * A run stops at a gate and asks a person to look at the exact values it is about to save. The
+ * request's `shown` payload is written for the machine: it carries the step's id, the action's name
+ * and the whole target ladder, including selectors. None of that is a person's business
+ * (DESIGN.md §2), so this module keeps only the two things the person is actually deciding about --
+ * the value and the row's own columns -- and names the decision request is sent as.
+ */
+
+import type { ApprovalDecisionBody } from "../types";
+
+/** One line of what the person is being shown. */
+export interface ShownLine {
+  label: string;
+  value: string;
+}
+
+/** The keys of `shown` that are engine internals and never reach the screen. */
+const INTERNAL_KEYS = new Set(["step", "action", "targets", "within", "frame", "id"]);
+
+/** "email_address" -> "Email address", so a spreadsheet column reads as words. */
+function columnName(key: string): string {
+  const spaced = key.replace(/[_-]+/g, " ").replace(/\s+/g, " ").trim();
+  if (spaced === "") return key;
+  return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+}
+
+/** A value a person can read. An object or an array is summarised, never dumped as JSON. */
+function readable(value: unknown): string | null {
+  if (value === null || value === undefined) return null;
+  if (typeof value === "string") return value.trim() === "" ? null : value;
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  if (Array.isArray(value)) {
+    const parts = value.map(readable).filter((part): part is string => part !== null);
+    return parts.length === 0 ? null : parts.join(", ");
+  }
+  return null;
+}
+
+/**
+ * What the person is shown, in order: the value the task is about to save, then the row's own
+ * columns. Everything the machine needs and a person does not -- the step's id, the action, the
+ * target ladder -- is left out.
+ */
+export function approvalLines(shown: Record<string, unknown> | null | undefined): ShownLine[] {
+  if (shown === null || shown === undefined) return [];
+  const lines: ShownLine[] = [];
+  const value = readable(shown["value"]);
+  if (value !== null) lines.push({ label: "The value it will save", value });
+
+  const record = shown["record"];
+  if (record !== null && typeof record === "object" && !Array.isArray(record)) {
+    for (const key of Object.keys(record as Record<string, unknown>).sort()) {
+      const entry = readable((record as Record<string, unknown>)[key]);
+      if (entry !== null) lines.push({ label: columnName(key), value: entry });
+    }
+  }
+
+  // Anything else the API sends, as long as it is not an engine internal and is readable.
+  for (const key of Object.keys(shown).sort()) {
+    if (key === "value" || key === "record" || INTERNAL_KEYS.has(key)) continue;
+    const entry = readable(shown[key]);
+    if (entry !== null) lines.push({ label: columnName(key), value: entry });
+  }
+  return lines;
+}
+
+/** The path the API already serves for a decision. */
+export const APPROVALS_PATH = "/api/v1/approvals";
+
+/**
+ * The body of a decision. The request id is the exact request the person was shown, and
+ * `decided_by` is never invented: without an operator identity there is nobody to record, so this
+ * refuses rather than sending a decision the ledger could not attribute.
+ */
+export function approvalBody(input: {
+  requestId: string;
+  decision: "approved" | "rejected";
+  operatorId: string | null;
+}): ApprovalDecisionBody {
+  if (input.operatorId === null || input.operatorId === "") {
+    throw new Error("Answering an approval needs the API's operator identity.");
+  }
+  return {
+    request_id: input.requestId,
+    decision: input.decision,
+    decided_by: input.operatorId,
+  };
+}
diff --git a/apps/web/src/lib/words.ts b/apps/web/src/lib/words.ts
index dbff147..1a47ce4 100644
--- a/apps/web/src/lib/words.ts
+++ b/apps/web/src/lib/words.ts
@@ -112,6 +112,84 @@ export function pauseReasonWords(reason: string | null): string | null {
   return `Paused: ${sentence(key)}. Sort that out, then resume.`;
 }
 
+/**
+ * Every word the engine uses that a person must never read, with the DESIGN.md §2 wording each one
+ * has to appear as instead. The engine-word test enforces this list, and `refusalWords` below is
+ * built on the same list, so the rule the tests check and the rule the page applies cannot drift
+ * apart.
+ */
+export const ENGINE_WORDS: ReadonlyArray<{ engine: string; pattern: RegExp; plain: string }> = [
+  { engine: "recipe", pattern: /recipe/i, plain: "task" },
+  { engine: "ledger", pattern: /ledger/i, plain: "never shown" },
+  { engine: "parked", pattern: /parked/i, plain: "needs your help" },
+  { engine: "record key", pattern: /record[\s_-]*key/i, plain: "the person's or thing's name" },
+  { engine: "verified", pattern: /verified/i, plain: "added, updated or done" },
+  { engine: "rung", pattern: /rung/i, plain: "never shown" },
+  { engine: "idempotency", pattern: /idempotency/i, plain: "never shown" },
+  // Whole tokens only, so an ordinary word or an id that merely contains the letters is not a hit.
+  { engine: "v1", pattern: /\bv1\b/i, plain: "never shown" },
+  { engine: "v2", pattern: /\bv2\b/i, plain: "never shown" },
+  { engine: "step_", pattern: /step_/i, plain: "one plain sentence" },
+  { engine: "fill-", pattern: /fill-/i, plain: "the element's own words" },
+  { engine: "click-", pattern: /click-/i, plain: "the element's own words" },
+];
+
+/** The engine words this text contains, so a caller can name the rule it would break. */
+export function engineWordsIn(text: string): string[] {
+  return ENGINE_WORDS.filter((rule) => rule.pattern.test(text)).map((rule) => rule.engine);
+}
+
+/** The API refused a request, and it had nothing a person could use to say why. */
+export const REFUSAL_FALLBACK = "The API refused that. Reload the page and try again.";
+
+/** The row moved on between the page loading and the button being pressed. */
+export const DEALT_WITH =
+  "Someone else has already dealt with this row. Reload the page to see where it stands.";
+
+const ALREADY_DEALT_WITH: readonly RegExp[] = [
+  /is not parked or failed/i,
+  /is not parked/i,
+  /does not exist/i,
+  /not the expected state/i,
+  /illegal ledger transition/i,
+];
+
+/** Said once when `GET /api/v1/operator` refuses: the API named nobody, so nobody can act. */
+export const OPERATOR_PROBLEM =
+  "The API has no operator identity, so this screen's actions are off";
+
+/** What to do about it, keeping the API's own variable name in view. */
+export const OPERATOR_NOTE =
+  "Set PROCESSLENS_OPERATOR_ID and restart the API, then reload this page.";
+
+/**
+ * The whole operator problem in one sentence, with the API's own `detail` inside it.
+ *
+ * One function for both screens that need it, so the wording cannot drift between them.
+ */
+export function operatorNote(detail: string | null | undefined): string {
+  const text = (detail ?? "").trim();
+  const said = text === "" ? "" : ` It said: ${text}.`;
+  return `${OPERATOR_PROBLEM}.${said} ${OPERATOR_NOTE}`;
+}
+
+/**
+ * A refusal, in the words a person can act on.
+ *
+ * The API's own `detail` is written for an engineer: it names a state, `run_record`, or
+ * `commit_attempted`, and DESIGN.md §2 and requirement 7 keep every one of those off the screen.
+ * The translation lives here, once, rather than in each page -- and the last word belongs to
+ * `engineWordsIn`, so a sentence that still carries an engine word is never shown whatever shape
+ * the API happens to use next.
+ */
+export function refusalWords(detail: string | null | undefined): string {
+  const text = (detail ?? "").trim();
+  if (text === "") return REFUSAL_FALLBACK;
+  if (ALREADY_DEALT_WITH.some((shape) => shape.test(text))) return DEALT_WITH;
+  if (engineWordsIn(text).length > 0) return REFUSAL_FALLBACK;
+  return text;
+}
+
 /** The states a run is still working through: `queued`, `running` or `paused`. */
 export function isOpenStatus(status: string | null): boolean {
   return status === "queued" || status === "running" || status === "paused";
diff --git a/apps/web/src/pages/NeedsHelp.tsx b/apps/web/src/pages/NeedsHelp.tsx
index f741cb8..507effb 100644
--- a/apps/web/src/pages/NeedsHelp.tsx
+++ b/apps/web/src/pages/NeedsHelp.tsx
@@ -2,15 +2,14 @@ import { type CSSProperties, useState } from "react";
 
 import { apiPost, errorText } from "../lib/api";
 import { useJson } from "../lib/useJson";
-import { plainReason, rowOutcome } from "../lib/words";
+import { plainReason, refusalWords, rowOutcome } from "../lib/words";
 import type { NeedsHelpRow, OperatorInfo } from "../types";
 import {
   DESTINATION_CHECK_LABEL,
   DESTINATION_CHECK_WHY,
-  OPERATOR_NOTE,
-  OPERATOR_PROBLEM,
   actionBody,
   actionGate,
+  operatorNote,
   recordActionLabel,
   recordActionPath,
   type RecordAction,
@@ -79,8 +78,9 @@ export function NeedsHelp(): JSX.Element {
       );
       help.reload();
     } catch (failure) {
-      // The API's own `detail` text, shown beside the button that caused it. Nothing is retried.
-      setErrors((current) => ({ ...current, [row.record_id]: errorText(failure) }));
+      // The API's own `detail` text, translated so no engine word reaches the person. Nothing is
+      // retried.
+      setErrors((current) => ({ ...current, [row.record_id]: refusalWords(errorText(failure)) }));
     } finally {
       setBusy(null);
     }
@@ -90,9 +90,7 @@ export function NeedsHelp(): JSX.Element {
     <div className="needs-help">
       {operatorProblem === null ? null : (
         <p className="operator-note in" style={slot(1)} role="status">
-          {OPERATOR_PROBLEM}
-          {": "}
-          <span className="operator-problem">{operatorProblem}</span> {OPERATOR_NOTE}
+          {operatorNote(operatorProblem)}
         </p>
       )}
 
diff --git a/apps/web/src/pages/RunDetail.tsx b/apps/web/src/pages/RunDetail.tsx
index cd721b1..9e53a17 100644
--- a/apps/web/src/pages/RunDetail.tsx
+++ b/apps/web/src/pages/RunDetail.tsx
@@ -2,20 +2,24 @@ import { type CSSProperties, useEffect, useState } from "react";
 import { Link, useParams } from "react-router-dom";
 
 import { apiPost, errorText } from "../lib/api";
-import { useJson } from "../lib/useJson";
+import { APPROVALS_PATH, approvalBody, approvalLines } from "../lib/approvals";
+import { POLL_INTERVAL_MS, useJson } from "../lib/useJson";
 import {
   isOpenStatus,
   minutesSavedWords,
+  operatorNote,
   pauseReasonWords,
   plainReason,
+  refusalWords,
   rowOutcome,
   runActions,
   runStatusWords,
 } from "../lib/words";
-import type { RecordRow, RunDetail as RunDetailPayload } from "../types";
+import type { OperatorInfo, RecordRow, RunDetail as RunDetailPayload } from "../types";
 import "./runs.css";
 
 type RunAction = "pause" | "resume" | "cancel";
+type Decision = "approved" | "rejected";
 
 /** The blur-in stagger for the sections (DESIGN.md §7). */
 function slot(index: number): CSSProperties {
@@ -61,9 +65,10 @@ export function RunDetail(): JSX.Element {
   const runPath = id === undefined ? null : `/api/v1/runs/${id}`;
   const recordsPath = id === undefined ? null : `/api/v1/runs/${id}/records`;
 
-  // The poll is 2 s while the run is still going, and `null` the moment it is not, so a finished
-  // run makes no further requests (PL-015's verified behaviour, carried forward).
-  const [pollMs, setPollMs] = useState<number | null>(2000);
+  // The poll starts only once the run is known to be open. Starting at 2 s would give a run that
+  // is already finished one more request two seconds after the page loaded, for nothing
+  // (PL-015's "does not poll a run that is already finished", carried forward).
+  const [pollMs, setPollMs] = useState<number | null>(null);
   const run = useJson<RunDetailPayload>(runPath, pollMs);
   const records = useJson<RecordRow[]>(recordsPath, pollMs);
 
@@ -72,12 +77,40 @@ export function RunDetail(): JSX.Element {
   const open = isOpenStatus(detail?.status ?? null);
 
   useEffect(() => {
-    const next = isOpenStatus(detail?.status ?? null) ? 2000 : null;
+    const next = isOpenStatus(detail?.status ?? null) ? POLL_INTERVAL_MS : null;
     setPollMs((current) => (current === next ? current : next));
   }, [detail]);
 
   const [busy, setBusy] = useState<RunAction | null>(null);
   const [refusal, setRefusal] = useState<{ action: RunAction; text: string } | null>(null);
+  // The operator identity, and the decision on the request the run is stopped at (PL-015's
+  // approval behaviour, carried forward): a request is answered as the person the API names, and
+  // when the API names nobody every decision is off and the page says why.
+  const operator = useJson<OperatorInfo>("/api/v1/operator");
+  const [deciding, setDeciding] = useState<Decision | null>(null);
+  const [decisionRefusal, setDecisionRefusal] = useState<string | null>(null);
+
+  async function decide(decision: Decision): Promise<void> {
+    const request = detail?.open_approval;
+    if (id === undefined || request === null || request === undefined) return;
+    setDeciding(decision);
+    setDecisionRefusal(null);
+    try {
+      await apiPost(
+        APPROVALS_PATH,
+        approvalBody({
+          requestId: request.id,
+          decision,
+          operatorId: operator.data?.operator_id ?? null,
+        }),
+      );
+      run.reload();
+    } catch (failure) {
+      setDecisionRefusal(refusalWords(errorText(failure)));
+    } finally {
+      setDeciding(null);
+    }
+  }
 
   async function act(action: RunAction): Promise<void> {
     if (id === undefined) return;
@@ -87,8 +120,9 @@ export function RunDetail(): JSX.Element {
       await apiPost(`/api/v1/runs/${id}/${action}`);
       run.reload();
     } catch (failure) {
-      // The API's own `detail` text, shown next to the button that caused it.
-      setRefusal({ action, text: errorText(failure) });
+      // The API's own `detail` text, translated so no engine word reaches the person, shown next to
+      // the button that caused it.
+      setRefusal({ action, text: refusalWords(errorText(failure)) });
     } finally {
       setBusy(null);
     }
@@ -114,6 +148,10 @@ export function RunDetail(): JSX.Element {
   const pauseReason = pauseReasonWords(detail.pause_reason);
   const started = stamp(detail.started_at);
   const finished = stamp(detail.finished_at);
+  const request = detail.open_approval;
+  const shown = approvalLines(request?.shown);
+  const operatorProblem = operator.error;
+  const decisionsOff = operatorProblem !== null;
 
   // "About 52 minutes saved": the rows this run finished would have taken about three minutes each
   // by hand, less the wall-clock the run itself took. Only a finished run has both times.
@@ -163,55 +201,56 @@ export function RunDetail(): JSX.Element {
         )}
         <div className="actions">
           {buttons.pause ? (
-            <>
+            <span className="run-action">
               <button
                 type="button"
-                className="btn quiet"
+                className="btn quiet run-action-pause"
                 disabled={busy !== null}
                 onClick={() => void act("pause")}
               >
                 Pause
               </button>
+              {/* The refusal sits in the same element as the button that caused it. */}
               {refusal?.action === "pause" ? (
-                <span className="refusal" role="status">
+                <span className="refusal action-error" role="status">
                   {refusal.text}
                 </span>
               ) : null}
-            </>
+            </span>
           ) : null}
           {buttons.resume ? (
-            <>
+            <span className="run-action">
               <button
                 type="button"
-                className="btn quiet"
+                className="btn quiet run-action-resume"
                 disabled={busy !== null}
                 onClick={() => void act("resume")}
               >
                 Resume
               </button>
               {refusal?.action === "resume" ? (
-                <span className="refusal" role="status">
+                <span className="refusal action-error" role="status">
                   {refusal.text}
                 </span>
               ) : null}
-            </>
+            </span>
           ) : null}
           {buttons.cancel ? (
-            <>
+            <span className="run-action">
               <button
                 type="button"
-                className="btn quiet"
+                className="btn quiet run-action-cancel"
                 disabled={busy !== null}
                 onClick={() => void act("cancel")}
               >
                 Cancel
               </button>
               {refusal?.action === "cancel" ? (
-                <span className="refusal" role="status">
+                <span className="refusal action-error" role="status">
                   {refusal.text}
                 </span>
               ) : null}
-            </>
+            </span>
           ) : null}
           <a className="btn quiet export" href={`/api/v1/runs/${detail.id}/results.csv`}>
             Export CSV
@@ -227,6 +266,61 @@ export function RunDetail(): JSX.Element {
         </section>
       )}
 
+      {/* PL-015's approval decision, carried forward: the run is stopped at a gate, and this is
+          where a person looks at the exact values and says yes or no. */}
+      {request === null ? null : (
+        <section className="panel in" style={slot(3)}>
+          <div className="panel-h">
+            <h3>Waiting for your decision</h3>
+            <span className="res live">Waiting</span>
+          </div>
+          <div className="approval">
+            <p className="approval-ask">
+              This run stopped before saving one row. Check these values, then say whether to go
+              ahead.
+            </p>
+            {shown.length === 0 ? null : (
+              <dl className="approval-values">
+                {shown.map((line, index) => (
+                  <div className="approval-line" key={`${line.label}-${index}`}>
+                    <dt>{line.label}</dt>
+                    <dd>{line.value}</dd>
+                  </div>
+                ))}
+              </dl>
+            )}
+            {decisionsOff ? (
+              <p className="operator-note" role="status">
+                {operatorNote(operatorProblem)}
+              </p>
+            ) : null}
+            <div className="actions">
+              <button
+                type="button"
+                className="btn primary approval-approved"
+                disabled={deciding !== null || decisionsOff}
+                onClick={() => void decide("approved")}
+              >
+                Go ahead
+              </button>
+              <button
+                type="button"
+                className="btn quiet approval-rejected"
+                disabled={deciding !== null || decisionsOff}
+                onClick={() => void decide("rejected")}
+              >
+                No, stop this row
+              </button>
+              {decisionRefusal === null ? null : (
+                <span className="refusal" role="status">
+                  {decisionRefusal}
+                </span>
+              )}
+            </div>
+          </div>
+        </section>
+      )}
+
       <section className="panel in" style={slot(3)}>
         <div className="panel-h">
           <h3>What happened to each row</h3>
diff --git a/apps/web/src/pages/needsHelpActions.ts b/apps/web/src/pages/needsHelpActions.ts
index 36c4ab5..6e87a42 100644
--- a/apps/web/src/pages/needsHelpActions.ts
+++ b/apps/web/src/pages/needsHelpActions.ts
@@ -13,20 +13,17 @@ import type { RecordActionBody } from "../types";
 /** The exact words the confirmation carries. The ticket fixes them. */
 export const DESTINATION_CHECK_LABEL = "I checked Odoo and it isn't there";
 
-/** Why the box is there, in one sentence, next to it. */
+/**
+ * Why the box is there, in one sentence, next to it.
+ */
 export const DESTINATION_CHECK_WHY =
   "We may already have saved this row before it went wrong, so look it up in Odoo and tick the box only if it is not there.";
 
 /**
- * Said once at the top of the page when `GET /api/v1/operator` refuses. The API's own `detail` text
- * follows it verbatim, so the person can see the words the server used.
+ * The wording of the operator problem lives in `lib/words.ts`, because the run page's decision
+ * panel needs the same sentence. Re-exported here so this page's imports stay in one place.
  */
-export const OPERATOR_PROBLEM =
-  "The API has no operator identity, so every action on this page is off";
-
-/** What to do about it, keeping the API's own variable name in view. */
-export const OPERATOR_NOTE =
-  "Set PROCESSLENS_OPERATOR_ID and restart the API, then reload this page.";
+export { OPERATOR_NOTE, OPERATOR_PROBLEM, operatorNote } from "../lib/words";
 
 export type RecordAction = "requeue" | "dismiss";
 
diff --git a/apps/web/src/pages/runs.css b/apps/web/src/pages/runs.css
index 929a062..66b04e2 100644
--- a/apps/web/src/pages/runs.css
+++ b/apps/web/src/pages/runs.css
@@ -60,6 +60,13 @@
 }
 
 /* A refusal sits next to the button that caused it, so a person knows what to do next. */
+.run-detail .run-action {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  flex-wrap: wrap;
+}
+
 .run-detail .refusal {
   color: var(--help);
   font-size: 13.5px;
@@ -76,6 +83,66 @@
   font-size: 14px;
 }
 
+/* The approval decision: the ask, the exact values a person is deciding about, then two buttons. */
+.run-detail .approval {
+  display: grid;
+  gap: 12px;
+  padding: 10px 20px 20px;
+}
+
+.run-detail .approval-ask {
+  margin: 0;
+  color: var(--ink-2);
+  font-size: 14px;
+}
+
+.run-detail .approval-values {
+  margin: 0;
+  display: grid;
+  gap: 0;
+  border: 1px solid var(--hair);
+  border-radius: 10px;
+  background: var(--glass-strong);
+}
+
+.run-detail .approval-line {
+  display: grid;
+  grid-template-columns: minmax(0, 12rem) minmax(0, 1fr);
+  gap: 12px;
+  padding: 9px 14px;
+  border-top: 1px solid var(--hair);
+}
+
+.run-detail .approval-line:first-child {
+  border-top: 0;
+}
+
+.run-detail .approval-line dt {
+  color: var(--muted);
+  font-size: 13px;
+}
+
+.run-detail .approval-line dd {
+  margin: 0;
+  color: var(--ink);
+  font-size: 14px;
+  overflow-wrap: anywhere;
+}
+
+.run-detail .approval .actions {
+  padding: 0;
+}
+
+.run-detail .operator-note {
+  margin: 0;
+  color: var(--ink-2);
+  font-size: 13.5px;
+}
+
+.run-detail .operator-problem {
+  color: var(--ink);
+}
+
 .run-detail .saved-fig {
   justify-self: start;
   min-width: 200px;
@@ -86,6 +153,11 @@
     margin-left: 0;
   }
 
+  .run-detail .approval-line {
+    grid-template-columns: minmax(0, 1fr);
+    gap: 2px;
+  }
+
   .runs .empty {
     padding: 4px 16px 18px;
   }
diff --git a/apps/web/tests/engineWords.test.tsx b/apps/web/tests/engineWords.test.tsx
index 267c107..1ac3504 100644
--- a/apps/web/tests/engineWords.test.tsx
+++ b/apps/web/tests/engineWords.test.tsx
@@ -23,11 +23,14 @@
  * before they can be rendered, which is exactly what the page checks below prove.
  */
 
+import { fireEvent } from "@testing-library/react";
 import { describe, expect, it } from "vitest";
 
+import { ENGINE_WORDS } from "../src/lib/words";
 import type {
   HomeSummary,
   NeedsHelpRow,
+  OperatorInfo,
   RecordRow,
   RunDetail as RunDetailPayload,
   RunSummary,
@@ -37,27 +40,8 @@ import { createFetchStub, renderApp, settle, type StubRoutes } from "./helpers";
 
 const OPERATOR_ID = "0f8fad5b-d9cb-469f-a165-70867728950e";
 
-interface Forbidden {
-  engine: string;
-  pattern: RegExp;
-  plain: string;
-}
-
-const FORBIDDEN: Forbidden[] = [
-  { engine: "recipe", pattern: /recipe/i, plain: "task" },
-  { engine: "ledger", pattern: /ledger/i, plain: "never shown" },
-  { engine: "parked", pattern: /parked/i, plain: "needs your help" },
-  { engine: "record key", pattern: /record[\s_-]*key/i, plain: "the person's or thing's name" },
-  { engine: "verified", pattern: /verified/i, plain: "added, updated or done" },
-  { engine: "rung", pattern: /rung/i, plain: "never shown" },
-  { engine: "idempotency", pattern: /idempotency/i, plain: "never shown" },
-  // Whole tokens only, so an ordinary word or an id that merely contains the letters is not a hit.
-  { engine: "v1", pattern: /\bv1\b/i, plain: "never shown" },
-  { engine: "v2", pattern: /\bv2\b/i, plain: "never shown" },
-  { engine: "step_", pattern: /step_/i, plain: "one plain sentence" },
-  { engine: "fill-", pattern: /fill-/i, plain: "the element's own words" },
-  { engine: "click-", pattern: /click-/i, plain: "the element's own words" },
-];
+/** The rule is `lib/words.ts`'s own list, so the test and the pages can never drift apart. */
+const FORBIDDEN = ENGINE_WORDS;
 
 /** Every forbidden word this text contains, so a failure names the rule it broke. */
 function engineWordsIn(text: string): string[] {
@@ -246,6 +230,69 @@ describe("every page shows only plain words", () => {
   }
 });
 
+/** The Needs help page's refusal, in the words the ledger itself sends. */
+const HELP_REFUSAL: StubRoutes = {
+  "/api/v1/records/": {
+    status: 409,
+    body: { detail: "run_record 3f0e1c2a-0000-4000-8000-00000000abcd is not parked" },
+  },
+};
+
+/** The run page's own refusal, in the same raw style: a state name and a sentence for an engineer. */
+const RUN_REFUSAL: StubRoutes = {
+  "/api/v1/runs/run-1/pause": {
+    status: 409,
+    body: { detail: "run run-1 is submitted_unverified and cannot be paused" },
+  },
+};
+
+describe("a refusal is shown in plain words too", () => {
+  it("Needs help says what happened, not the ledger's own sentence, when the API answers 409", async () => {
+    // A row that never reached a commit, so Try again is live and the refusal can be triggered.
+    const stub = createFetchStub(
+      routes({
+        ...HELP_REFUSAL,
+        "/api/v1/needs-help": { body: [{ ...HELP_ROWS[0], commit_attempted: false }] },
+      }),
+    );
+    const view = renderApp("/needs-help");
+    await settle();
+
+    const bell = view.container.querySelector<HTMLButtonElement>(".record-requeue");
+    expect(bell, "the page offers its actions").not.toBeNull();
+    fireEvent.click(bell as HTMLButtonElement);
+    await settle();
+
+    const text = visibleText(view.container);
+    const found = engineWordsIn(text);
+    expect(found, `the refusal must not carry: ${found.join(", ")}`).toEqual([]);
+    expect(text).not.toContain("run_record");
+    expect(text).toContain("already dealt with this row");
+    stub.restore();
+    view.unmount();
+  });
+
+  it("a run page says what happened, not the run's own state, when the API answers 409", async () => {
+    const stub = createFetchStub(
+      routes({
+        ...RUN_REFUSAL,
+        "/api/v1/runs/run-1": { body: { ...RUN_DETAIL, status: "running", finished_at: null } },
+      }),
+    );
+    const view = renderApp("/runs/run-1");
+    await settle();
+
+    fireEvent.click(view.container.querySelector(".run-action-pause") as HTMLButtonElement);
+    await settle();
+
+    const text = visibleText(view.container);
+    const found = engineWordsIn(text);
+    expect(found, `the refusal must not carry: ${found.join(", ")}`).toEqual([]);
+    stub.restore();
+    view.unmount();
+  });
+});
+
 describe("the sample data", () => {
   it("carries no forbidden word in anything a page shows", () => {
     // An engine state or a count name is an identifier the API sends, and every page maps it
diff --git a/apps/web/tests/needsHelp.test.tsx b/apps/web/tests/needsHelp.test.tsx
index f93e49e..7e22b14 100644
--- a/apps/web/tests/needsHelp.test.tsx
+++ b/apps/web/tests/needsHelp.test.tsx
@@ -32,8 +32,22 @@ const OPERATOR_ID = "0f8fad5b-d9cb-469f-a165-70867728950e";
 
 /** The API's own words for a missing operator identity (services/api/main.py). */
 const OPERATOR_503 = "PROCESSLENS_OPERATOR_ID is not set, so there is no operator id to act as";
-/** The API's own words when the ledger will not make the move (services/api/runs.py). */
-const CONFLICT = "record record-1 is parked and commit_attempted needs a destination check";
+
+/*
+ * The 409 the API really sends comes from the ledger itself: `str(exc)` of a `StateConflict` or the
+ * database trigger's own text (services/api/runs.py, packages/ledger/records.py,
+ * db/migrations/0003_run_orchestration.sql). It is written for an engineer -- it names a state and
+ * the table row -- so it must never be what the person reads. These two constants are the two
+ * shapes that actually arrive: the state conflict and the trigger's refusal.
+ */
+const REAL_CONFLICT = "run_record 3f0e1c2a-0000-4000-8000-00000000abcd is not parked";
+const TRIGGER_CONFLICT =
+  "run_record 3f0e1c2a-0000-4000-8000-00000000abcd was commit-attempted; parked -> skipped requires a fresh destination check";
+/** What the person reads instead: one sentence about what happened and what to do. */
+const DEALT_WITH =
+  "Someone else has already dealt with this row. Reload the page to see where it stands.";
+/** The same, when the refusal's shape is one we cannot characterise at all. */
+const REFUSAL_FALLBACK = "The API refused that. Reload the page and try again.";
 
 function sampleRow(over: Partial<NeedsHelpRow> = {}): NeedsHelpRow {
   return {
@@ -242,11 +256,11 @@ describe("the destination check gates a commit-attempted row on the page", () =>
   });
 });
 
-describe("a refused request shows the API's detail text next to the button", () => {
+describe("a refused request shows one plain sentence next to the button", () => {
   it("shows a 409 from Dismiss beside the Dismiss button and does not retry", async () => {
     const stub = createFetchStub(
       routes([sampleRow({ commit_attempted: false })], {
-        "/api/v1/records/record-1/dismiss": { status: 409, body: { detail: CONFLICT } },
+        "/api/v1/records/record-1/dismiss": { status: 409, body: { detail: REAL_CONFLICT } },
       }),
     );
     const view = renderApp("/needs-help");
@@ -257,9 +271,13 @@ describe("a refused request shows the API's detail text next to the button", ()
 
     const cell = view.container.querySelector<HTMLElement>(".row-actions");
     const error = cell?.querySelector<HTMLElement>(".action-error");
-    expect(error?.textContent).toBe(CONFLICT);
+    expect(error?.textContent).toBe(DEALT_WITH);
     // "next to the button": the same cell the Dismiss button lives in.
     expect(button(view.container, ".record-dismiss").closest(".row-actions")).toBe(cell);
+    // The API's own words name a state and a table row, and a person never reads either.
+    expect(view.container.textContent).not.toContain("run_record");
+    expect(view.container.textContent).not.toContain("parked");
+    expect(view.container.textContent).not.toContain("3f0e1c2a");
 
     expect(callsTo(stub, "/api/v1/records/record-1/dismiss")).toBe(1);
     await settle();
@@ -268,10 +286,10 @@ describe("a refused request shows the API's detail text next to the button", ()
     view.unmount();
   });
 
-  it("shows a 409 from Try again beside the Try again button", async () => {
+  it("shows a 409 from Try again beside the Try again button, in the same plain words", async () => {
     const stub = createFetchStub(
       routes([sampleRow({ commit_attempted: false })], {
-        "/api/v1/records/record-1/requeue": { status: 409, body: { detail: CONFLICT } },
+        "/api/v1/records/record-1/requeue": { status: 409, body: { detail: TRIGGER_CONFLICT } },
       }),
     );
     const view = renderApp("/needs-help");
@@ -281,8 +299,10 @@ describe("a refused request shows the API's detail text next to the button", ()
     await settle();
 
     const cell = view.container.querySelector<HTMLElement>(".row-actions");
-    expect(cell?.querySelector(".action-error")?.textContent).toBe(CONFLICT);
+    expect(cell?.querySelector(".action-error")?.textContent).toBe(REFUSAL_FALLBACK);
     expect(button(view.container, ".record-requeue").closest(".row-actions")).toBe(cell);
+    expect(view.container.textContent).not.toContain("commit-attempted");
+    expect(view.container.textContent).not.toContain("destination check");
     stub.restore();
     view.unmount();
   });
@@ -307,10 +327,8 @@ describe("the operator identity", () => {
     // It refuses to act, and it says why -- including the API's own words and the variable to set.
     const note = view.container.querySelector<HTMLElement>(".operator-note");
     expect(note?.textContent).toContain(OPERATOR_PROBLEM);
+    expect(note?.textContent).toContain(OPERATOR_503);
     expect(note?.textContent).toContain("PROCESSLENS_OPERATOR_ID");
-    expect(view.container.querySelector<HTMLElement>(".operator-problem")?.textContent).toBe(
-      OPERATOR_503,
-    );
 
     fireEvent.click(button(view.container, ".record-dismiss"));
     await settle();
diff --git a/apps/web/tests/runs.test.tsx b/apps/web/tests/runs.test.tsx
index d55b94b..e140714 100644
--- a/apps/web/tests/runs.test.tsx
+++ b/apps/web/tests/runs.test.tsx
@@ -8,12 +8,17 @@ import { act, fireEvent, screen } from "@testing-library/react";
 import { afterEach, describe, expect, it, vi } from "vitest";
 
 import type { RecordRow, RunDetail as RunPayload, RunSummary } from "../src/types";
+import { POLL_INTERVAL_MS } from "../src/lib/useJson";
 import { callsTo, createFetchStub, renderApp, settle, type FetchStub } from "./helpers";
 
+const OPERATOR_ID = "0f8fad5b-d9cb-469f-a165-70867728950e";
+const OPERATOR_503 = "PROCESSLENS_OPERATOR_ID is not set, so there is no operator id to act as";
+
 /* Every path the Shell asks for as well, so a page test never hits the real API. */
 const SHELL = {
   "/api/v1/needs-help": { body: [] },
   "/api/v1/executor/session": { body: { attached: false } },
+  "/api/v1/operator": { body: { operator_id: OPERATOR_ID } },
 };
 
 let stub: FetchStub | null = null;
@@ -64,6 +69,26 @@ function record(overrides: Partial<RecordRow> = {}): RecordRow {
   };
 }
 
+/** The request a paused run is stopped at, with the engine internals the API really sends. */
+function sampleApproval() {
+  return {
+    id: "approval-1",
+    run_record_id: "rr-1",
+    // The API sends the step's id, the action's name and the whole target ladder. None of it may
+    // reach the screen, so this fixture carries all three.
+    step_id: "save-lead",
+    kind: "commit",
+    shown: {
+      step: "save-lead",
+      action: "click",
+      targets: [{ by: "css", selector: "#lead-save" }],
+      value: "New enquiry",
+      record: { email: "priya@example.com", company_name: "Acme" },
+    },
+    created_at: "2026-10-15T09:10:00Z",
+  };
+}
+
 function buttonNames(): string[] {
   return screen
     .getAllByRole("button")
@@ -222,7 +247,7 @@ describe("one run", () => {
       "/api/v1/runs/run-1/pause": { status: 409, body: { detail: "run run-1 is completed" } },
       "/api/v1/runs/run-1": { body: runDetail({ status: "running" }) },
     });
-    renderApp("/runs/run-1");
+    const view = renderApp("/runs/run-1");
     await settle();
 
     await act(async () => {
@@ -230,6 +255,11 @@ describe("one run", () => {
     });
     await settle();
 
+    // The API's own words, in the same element as the button that caused them (PL-015's
+    // `closest(...)` placement assertion, carried forward against this page's own markup).
+    const pause = view.container.querySelector<HTMLButtonElement>(".run-action-pause");
+    const group = pause?.closest(".run-action");
+    expect(group?.querySelector(".action-error")?.textContent).toBe("run run-1 is completed");
     expect(screen.getByText("run run-1 is completed")).toBeTruthy();
   });
 
@@ -256,6 +286,141 @@ describe("one run", () => {
   });
 });
 
+describe("a run stopped for your decision", () => {
+  it("shows what it is about to save, in words, and never the step id or the selector", async () => {
+    stub = createFetchStub({
+      ...SHELL,
+      "/api/v1/runs/run-1/records": { body: [] },
+      "/api/v1/runs/run-1": {
+        body: runDetail({
+          status: "paused",
+          pause_reason: "awaiting_approval",
+          open_approval: sampleApproval(),
+        }),
+      },
+    });
+    renderApp("/runs/run-1");
+    await settle();
+
+    expect(screen.getByText("Waiting for your decision")).toBeTruthy();
+    expect(screen.getByText("The value it will save")).toBeTruthy();
+    expect(screen.getByText("New enquiry")).toBeTruthy();
+    // The row's own columns, named as the person's spreadsheet names them.
+    expect(screen.getByText("Email")).toBeTruthy();
+    expect(screen.getByText("priya@example.com")).toBeTruthy();
+    expect(screen.getByText("Company name")).toBeTruthy();
+    expect(screen.getByText("Acme")).toBeTruthy();
+    // The API's own payload carries these, and none of them is a person's business.
+    const page = screen.getByRole("main");
+    expect(page.textContent).not.toContain("save-lead");
+    expect(page.textContent).not.toContain("lead-save");
+    expect(page.textContent).not.toContain("targets");
+  });
+
+  it("answers the request as the operator the API names, and asks for nothing else", async () => {
+    const fetchStub = createFetchStub({
+      ...SHELL,
+      "/api/v1/runs/run-1/records": { body: [] },
+      "/api/v1/runs/run-1": {
+        body: runDetail({
+          status: "paused",
+          pause_reason: "awaiting_approval",
+          open_approval: sampleApproval(),
+        }),
+      },
+      "/api/v1/approvals": {
+        body: { approval_id: "a-1", request_id: "approval-1", decision: "approved", run_id: "run-1", resumed: true },
+      },
+    });
+    stub = fetchStub;
+    renderApp("/runs/run-1");
+    await settle();
+
+    await act(async () => {
+      fireEvent.click(screen.getByRole("button", { name: "Go ahead" }));
+    });
+    await settle();
+
+    const posts = fetchStub.requests.filter((call) => call.path === "/api/v1/approvals");
+    expect(posts).toHaveLength(1);
+    expect(posts[0]?.body).toEqual({
+      request_id: "approval-1",
+      decision: "approved",
+      decided_by: OPERATOR_ID,
+    });
+  });
+
+  it("says no without inventing a reason the person did not give", async () => {
+    const fetchStub = createFetchStub({
+      ...SHELL,
+      "/api/v1/runs/run-1/records": { body: [] },
+      "/api/v1/runs/run-1": {
+        body: runDetail({
+          status: "paused",
+          pause_reason: "awaiting_approval",
+          open_approval: sampleApproval(),
+        }),
+      },
+      "/api/v1/approvals": {
+        body: { approval_id: "a-2", request_id: "approval-1", decision: "rejected", run_id: "run-1", resumed: true },
+      },
+    });
+    stub = fetchStub;
+    renderApp("/runs/run-1");
+    await settle();
+
+    await act(async () => {
+      fireEvent.click(screen.getByRole("button", { name: "No, stop this row" }));
+    });
+    await settle();
+
+    const posts = fetchStub.requests.filter((call) => call.path === "/api/v1/approvals");
+    expect(posts).toHaveLength(1);
+    expect(posts[0]?.body).toEqual({
+      request_id: "approval-1",
+      decision: "rejected",
+      decided_by: OPERATOR_ID,
+    });
+  });
+
+  it("disables both decisions and says why when the API names no operator", async () => {
+    stub = createFetchStub({
+      ...SHELL,
+      "/api/v1/operator": { status: 503, body: { detail: OPERATOR_503 } },
+      "/api/v1/runs/run-1/records": { body: [] },
+      "/api/v1/runs/run-1": {
+        body: runDetail({
+          status: "paused",
+          pause_reason: "awaiting_approval",
+          open_approval: sampleApproval(),
+        }),
+      },
+    });
+    renderApp("/runs/run-1");
+    await settle();
+
+    expect(screen.getByRole("button", { name: "Go ahead" }).hasAttribute("disabled")).toBe(true);
+    expect(
+      screen.getByRole("button", { name: "No, stop this row" }).hasAttribute("disabled"),
+    ).toBe(true);
+    // It refuses to act, and it says why, keeping the API's own words.
+    expect(screen.getByText(/PROCESSLENS_OPERATOR_ID/)).toBeTruthy();
+    expect(screen.getByText(new RegExp(OPERATOR_503))).toBeTruthy();
+  });
+
+  it("shows no decision panel when the run is not waiting for one", async () => {
+    stub = createFetchStub({
+      ...SHELL,
+      "/api/v1/runs/run-1/records": { body: [] },
+      "/api/v1/runs/run-1": { body: runDetail({ status: "running" }) },
+    });
+    renderApp("/runs/run-1");
+    await settle();
+
+    expect(screen.queryByText("Waiting for your decision")).toBeNull();
+  });
+});
+
 describe("the page's poll", () => {
   it("asks every two seconds while the run is open and stops for good once it finishes", async () => {
     vi.useFakeTimers();
@@ -296,5 +461,50 @@ describe("the page's poll", () => {
     });
     expect(callsTo(fetchStub, "/api/v1/runs/run-1")).toBe(afterFinish);
   });
+
+  it("asks nothing at all of a run that is already finished", async () => {
+    vi.useFakeTimers({ toFake: ["setInterval", "clearInterval"] });
+    const fetchStub = createFetchStub({
+      ...SHELL,
+      "/api/v1/runs/run-1/records": { body: [] },
+      "/api/v1/runs/run-1": { body: runDetail({ status: "failed" }) },
+    });
+    stub = fetchStub;
+
+    renderApp("/runs/run-1");
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(0);
+    });
+    const afterLoad = callsTo(fetchStub, "/api/v1/runs/run-1");
+    expect(afterLoad).toBeGreaterThan(0);
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(10_000);
+    });
+    expect(callsTo(fetchStub, "/api/v1/runs/run-1")).toBe(afterLoad);
+  });
+
+  it("polls on the interval the design fixes", () => {
+    expect(POLL_INTERVAL_MS).toBe(2000);
+  });
+});
+
+describe("a hostile value is rendered as text", () => {
+  it("shows a row's key and reason as characters, and never as elements", async () => {
+    const HOSTILE = '<img src=x onerror=alert(1)>ACME-1';
+    stub = createFetchStub({
+      ...SHELL,
+      "/api/v1/runs/run-1/records": {
+        body: [record({ record_key: HOSTILE, state: "parked", reason: HOSTILE })],
+      },
+      "/api/v1/runs/run-1": { body: runDetail() },
+    });
+    const view = renderApp("/runs/run-1");
+    await settle();
+
+    expect(view.container.querySelectorAll("img")).toHaveLength(0);
+    expect(view.container.querySelectorAll("script")).toHaveLength(0);
+    expect(screen.getByText(HOSTILE)).toBeTruthy();
+  });
 });
 

From 9d7ff76fba729bdca9fee6829938777d81740770 Mon Sep 17 00:00:00 2001
From: Jayanth Vasupilli <156448548+jayanthvee@users.noreply.github.com>
Date: Thu, 15 Oct 2026 16:50:04 -0700
Subject: [PATCH 09/12] fix(api): keep an API miss a JSON 404, and stop polling
 a finished run

An unknown path under /api/ was answering the app shell at 200, because the SPA fallback served index.html for any extensionless miss. A caller parsing JSON then waited on a request that had actually failed. Only a client-side route gets the page now; anything under api/ keeps the API's own 404.

That test also caught a Windows-only bug in the same change: Starlette normalises the mount's path with os.path.normpath, so on this machine the separators are backslashes and the api/ prefix test silently never matched. Normalised back before the test, so it behaves the same here and on the deployment.

The run page's poll now starts only once the run is known to be open: starting at two seconds gave a run that was already finished one more request after the page loaded, which PL-015 had a test against.
---
 services/api/main.py          | 29 +++++++++++++++++++++++------
 tests/api/test_web_serving.py | 13 +++++++++++++
 2 files changed, 36 insertions(+), 6 deletions(-)

diff --git a/services/api/main.py b/services/api/main.py
index 814baf6..708d361 100644
--- a/services/api/main.py
+++ b/services/api/main.py
@@ -124,20 +124,37 @@ class SpaStaticFiles(StaticFiles):
 
     A person can refresh on ``/runs/abc``. No such file exists, so the mount would answer 404 and
     the page would never load. A path with no file extension therefore answers ``index.html`` and
-    the router inside the page decides what to draw. A missing *asset* -- ``*.js``, ``*.css``,
-    ``*.png`` and the rest -- still 404s, so a broken build is visible rather than a page that
-    quietly serves a stylesheet that is not there.
+    the router inside the page decides what to draw.
+
+    Two things still 404 rather than answering the page, on purpose:
+
+    * a missing *asset* -- ``*.js``, ``*.css``, ``*.png`` and the rest -- so a broken build is
+      visible instead of a page that quietly serves a stylesheet that is not there;
+    * anything under ``/api/``, so a mistyped API path stays the JSON 404 the API itself would
+      send. Handing the page's HTML to an API caller would turn a plain 404 into a 200 whose body
+      no caller can parse.
     """
 
+    # The prefix the API owns; a miss under it is the API's 404, never the page.
+    API_PREFIX = "api/"
+
     async def get_response(self, path: str, scope: MutableMapping[str, Any]) -> Response:
-        """Answer the file, or the page for a route, or 404 for a missing asset."""
+        """Answer the file, or the page for a route, or 404 for a missing asset or API path.
+
+        ``path`` has already been through ``os.path.normpath``, so on Windows its separators are
+        backslashes; they are normalised back before the prefix test, or ``/api/...`` would slip
+        past it on this machine and not on the deployment.
+        """
+        relative = path.replace("\\", "/").lstrip("/")
+        if relative.startswith(self.API_PREFIX) or Path(relative).suffix:
+            return await super().get_response(path, scope)
         try:
             response = await super().get_response(path, scope)
         except StarletteHTTPException as exc:
-            if exc.status_code != 404 or Path(path).suffix:
+            if exc.status_code != 404:
                 raise
             return await super().get_response("index.html", scope)
-        if response.status_code == 404 and not Path(path).suffix:
+        if response.status_code == 404:
             return await super().get_response("index.html", scope)
         return response
 
diff --git a/tests/api/test_web_serving.py b/tests/api/test_web_serving.py
index 378d15d..38a61f5 100644
--- a/tests/api/test_web_serving.py
+++ b/tests/api/test_web_serving.py
@@ -37,3 +37,16 @@ def test_a_missing_asset_still_404s(client: TestClient) -> None:
     response = client.get("/assets/does-not-exist-0000.js")
 
     assert response.status_code == 404, response.text
+
+
+def test_an_unknown_api_path_still_404s_as_json(client: TestClient) -> None:
+    """A miss under `/api/` is the API's own 404, never the page: a caller gets JSON, not HTML.
+
+    Otherwise a mistyped API path would answer 200 with the app shell, and a page that parses JSON
+    would sit on "Loading…" for a request that actually failed.
+    """
+    response = client.get("/api/v1/nope")
+
+    assert response.status_code == 404, response.text
+    assert response.headers["content-type"].startswith("application/json")
+    assert ROOT_ELEMENT not in response.text

From 9e9d5b1acd684513feb271a40688dab47c9c2b9f Mon Sep 17 00:00:00 2001
From: Jayanth Vasupilli <156448548+jayanthvee@users.noreply.github.com>
Date: Thu, 15 Oct 2026 16:52:48 -0700
Subject: [PATCH 10/12] docs(report): record PL-023's pages, its data, its
 gates and the review's two majors

The report lists each page with what data it shows, the gates with their real output, the PL-015 behaviour carried into React and the one assertion deliberately not carried, the four-builder split, the phone-width work the browser measurement forced, and what T1 should look at hardest.
---
 internal/agent/reports/PL-023.md | 282 +++++++++++++++++++++++++++++++
 1 file changed, 282 insertions(+)
 create mode 100644 internal/agent/reports/PL-023.md

diff --git a/internal/agent/reports/PL-023.md b/internal/agent/reports/PL-023.md
new file mode 100644
index 0000000..327c7a5
--- /dev/null
+++ b/internal/agent/reports/PL-023.md
@@ -0,0 +1,282 @@
+# PL-023 — The web app: shell, Home, Tasks, Runs and Needs help
+
+Status: **complete** — branch `pl-023`, pushed for T1. No e2e was run in this ticket.
+Reviewer: an independent read-only review of the branch ran before this report; its findings and
+what was done about each are in "The independent review" below.
+
+## What this ticket delivered
+
+`apps/web` is now React 18 + TypeScript + Vite in the approved look, and `services/api` serves it at
+`/`. Nine commits, 73 files, +7,305 / −2,283.
+
+| Path | What it is |
+| --- | --- |
+| `apps/web/src/styles/tokens.css` | The design tokens, copied verbatim from `internal/docs/design/home-mock.html` |
+| `apps/web/src/styles/global.css` | The mock's primitives ported: the fog background, the focus ring, the gold primary button, the glass panels, the tables, the live dot, the blur-in, the reduced-motion block, the phone rules |
+| `apps/web/src/shell/` | `Shell`, `Sidebar` (DESIGN.md §6), `Header` (title, Ctrl K search, one primary action, avatar), `Search`, `Icons` (the mock's sprite), `EmptyState`, `shell.css` |
+| `apps/web/src/lib/` | `api.ts` (client + `errorText`), `useJson.ts` (`POLL_INTERVAL_MS`, poll-or-not), `words.ts` (the whole vocabulary), `approvals.ts`, `steps.ts` |
+| `apps/web/src/pages/` | `Home`, `Tasks`, `TaskDetail`, `Runs`, `RunDetail`, `NeedsHelp`, `ComingSoon` + their CSS |
+| `services/api/home.py` | `GET /api/v1/home`, `/needs-help`, `/tasks` |
+| `services/api/hub.py` | one read-only route, `GET /api/v1/executor/session` |
+| `services/api/main.py` | the SPA-aware static mount |
+| `apps/web/tests/` | 10 files, 98 tests, incl. `engineWords.test.tsx` (requirement 7) |
+| `tests/api/` | `test_home_api.py`, `test_web_serving.py`, `test_hub_session_state.py` |
+
+The PL-015 plain-TypeScript operator page and its six test files were deleted; their behaviour was
+carried into React (see "Carried forward from PL-015").
+
+## Acceptance criteria
+
+### Gates — all green, real output
+
+```
+$ npm --prefix apps/web run check
+  > tsc --noEmit                                 (clean)
+  Test Files  10 passed (10)
+       Tests  98 passed (98)
+  ✓ built in 257ms                               WEB EXIT: 0
+
+$ .\.venv\Scripts\python.exe -m pytest -q
+  697 passed, 1 warning in 95.64s (0:01:35)      EXIT: 0
+  (the warning is the pre-existing starlette/httpx deprecation from fastapi's testclient)
+
+$ .\.venv\Scripts\ruff.exe check .
+  All checks passed!
+$ .\.venv\Scripts\ruff.exe format --check .
+  222 files already formatted                    EXIT: 0
+
+$ npm --prefix apps/extension run check
+  Test Files  28 passed (28)
+       Tests  371 passed (371)
+  package validation passed                      EXT EXIT: 0
+```
+
+### `services/api` serves the built app at `/`, every sidebar route loads, no console errors
+
+Verified in a real browser against the real API (Chromium via Playwright, `uvicorn` on a scratch
+database of synthetic rows). Every route below answered 200 with its own page title, and the
+console reported **no** errors and **no** page errors on any of them:
+
+```
+/                  title='Home'                 22 rows done this week.
+/needs-help        title='Needs help'            3 waiting
+/tasks             title='Tasks'                 3 saved
+/runs              title='Runs'                  All runs
+/spreadsheets      title='Spreadsheets'          …will appear here · Coming soon
+/documents         title='Documents'             …will appear here · Coming soon
+/saved-answers     title='Saved answers'         …will appear here · Coming soon
+/apps              title='Apps'                  …will appear here · Coming soon
+/settings          title='Settings'              …will appear here · Coming soon
+/help              title='Help'                  …will appear here · Coming soon
+/teach             title='Teach a new task'      …Coming next
+console problems: none
+```
+
+The API routes under the same server: `/health` 200, `/api/v1/home` 200 JSON (the real shape),
+`/api/v1/needs-help` 200 `[]`/JSON, `/api/v1/tasks` 200 JSON, `/api/v1/runs` 200 JSON,
+`/api/v1/executor/session` 200 `{"attached":false}`, a missing asset 404 JSON, an unknown
+`/api/v1/*` path 404 JSON.
+
+### The report lists each page with what data it shows
+
+- **Home `/`** — `GET /api/v1/home`. The headline "22 rows done this week. / 2 need you." from
+  `counts.done` and `counts.needs_help`; the lede from `counts.already_there` ("4 rows were already
+  there."); the gold panel `durationWords(minutes_saved)` over "Time saved this week"; Needs your
+  help from the top 3 of `needs_help` (the row's name, `plainReason`, the task name); Running now
+  from `running` (the live dot, the task name, `done/total` on the bar, "13 of 20 done", "2 already
+  there"); My tasks from `tasks` — name, the app, `relativeTime(last_run.started_at)`, the result,
+  one quiet button. With nothing done and nothing needing help the headline is "Nothing has run
+  yet." and the quiet Teach link appears.
+- **Needs help `/needs-help`** — `GET /api/v1/needs-help`, plus `GET /api/v1/operator`. Each row:
+  the row's name as the title, `plainReason(reason, state)` as the sentence, the task name as the
+  meta line, `rowOutcome(state)` as the dot plus word, and Try again / Dismiss. A
+  `commit_attempted` row carries the destination-check box and its one-sentence explanation.
+- **Tasks `/tasks`** — `GET /api/v1/tasks`: name (a link to the task), the app (host of the recipe's
+  first allowed origin), last run, result, one quiet button. Empty: "The tasks you teach will appear
+  here." + "Teach your first task" → `/teach`.
+- **Task `/tasks/:id`** — `GET /api/v1/tasks` for the task, `GET /api/v1/recipes/{version_id}` for
+  the document, `GET /api/v1/runs` for its runs. Read-only: the name, the app, every step in one
+  plain sentence, and its runs with their result and progress.
+- **Runs `/runs`** — `GET /api/v1/runs`: task, started, status, "13 of 20 done" over a bar, Open.
+- **Run `/runs/:id`** — `GET /api/v1/runs/{id}` + `/records`: live progress, Pause/Resume/Cancel,
+  the pause reason in words, the times, Export CSV, the time saved for a finished run, the approval
+  decision panel when the run is waiting for one, and the results table (row name → outcome →
+  reason).
+- **ComingSoon** routes (`/teach`, `/spreadsheets`, `/documents`, `/saved-answers`, `/apps`,
+  `/settings`, `/help`) — one sentence chosen from the path, plus "Coming soon".
+
+## The plain-words rule (requirement 7)
+
+`apps/web/tests/engineWords.test.tsx` renders Home, Needs help, Tasks, Task detail, Runs, Run detail
+and ComingSoon with sample data, asserts each really rendered its data (so a blank page cannot pass),
+and fails if the visible text carries `recipe`, `ledger`, `parked`, `record key`, `verified`, `rung`,
+`idempotency`, `v1`, `v2`, `step_`, `fill-` or `click-`. The list itself lives in
+`apps/web/src/lib/words.ts` (`ENGINE_WORDS`) and the test imports it, so the rule the test enforces
+and the rule the pages apply cannot drift apart. It also carries a case for the refusal state of both
+actionable pages (see the review, MAJOR 1).
+
+## Carried forward from PL-015
+
+The old page's verified behaviour, and where each assertion now lives:
+
+| PL-015 assertion | Now |
+| --- | --- |
+| Both buttons disabled until the unticked destination check is ticked, enabled after, disabled again when cleared | `apps/web/tests/needsHelp.test.tsx` — "the destination check gates a commit-attempted row on the page" |
+| A row that never reached a commit needs no tick, sends `{}` | same file, page test + `actionGate`/`actionBody` unit tests |
+| Disabled while the API has no operator id | `actionGate` unit test, and the 503 page test |
+| The operator 503 disables everything and says why, keeping the API's own words | "disables every action and says why when the endpoint answers 503" |
+| A 409's text sits next to the button that caused it, and nothing retries | both refusal tests (`closest(".row-actions")`, POST count stays 1) |
+| Pause/Resume/Cancel follow the status, incl. `queued` | `runs.test.tsx` — "offers Pause and Cancel while it is going…" (running, queued, paused) |
+| Nothing offered once the run is finished | same file, "offers nothing once the run is finished" |
+| The pause reason in words | same file, "puts the pause reason into words…" over the whole `PAUSE_REASONS` table in `words.test.ts` |
+| The refusal sits in the same element as the button that caused it | same file, `closest(".run-action")` |
+| The poll is 2 s, and stops for good when the run ends | same file, "asks every two seconds… and stops for good" |
+| Nothing polls a run that is already finished | same file, "asks nothing at all of a run that is already finished" (this was a live regression — see MAJOR 4) |
+| A hostile value lands as text | same file, "a hostile value is rendered as text" |
+| The approval decision (values shown, `decided_by` in the body, disabled on 503) | same file, "a run stopped for your decision" — four tests |
+| `POLL_INTERVAL_MS === 2000` | same file, "polls on the interval the design fixes" |
+
+**Not carried, on purpose.** The old page rendered a per-state count table
+(`.count-parked .count-value`, `.count-total .count-label`). Requirement 5 asks the run page for live
+progress, pause/resume/cancel, a results table and Export CSV, so the counts are now the ones a
+person reads in the panel ("13 of 20 done", "2 already there") and the results table's own dot plus
+word per row. The raw per-state counters are gone rather than hidden; if T1 wants them back as a
+small panel they are one `Object.entries(counts)` away.
+
+## The independent review, and what was done
+
+A read-only reviewer was sent at the branch with one instruction: try to refute it. It found two
+major defects, and both were real.
+
+**MAJOR 1 — the API's own refusal text reached the screen.** `services/api/runs.py` answers a 409
+with `str(exc)`, which is the ledger's own words: `run_record <id> is not parked`, or the database
+trigger's `… was commit-attempted; parked -> skipped requires a fresh destination check`. Both
+actionable pages printed it verbatim, so a person could read a table-row name, a state and a uuid —
+and the branch's own `needsHelp.test.tsx` *asserted* that string was shown. Reproducible by two
+clicks on the same row in two tabs.
+
+Fixed: `lib/words.ts` now owns the translation (`refusalWords`). A refusal whose shape says the row
+was already dealt with becomes "Someone else has already dealt with this row. Reload the page to see
+where it stands."; anything else is measured against `ENGINE_WORDS` and replaced with a plain
+sentence if it still carries an engine word. `engineWords.test.tsx` now renders both pages in their
+refusal state with the ledger's real 409 bodies and fails on the same rule, and the two tests that
+had asserted the raw text now assert that the raw text never reaches the person.
+
+**MAJOR 2 — PL-015's approval decision was missing.** Nothing read `open_approval`, so a run paused
+`awaiting_approval` told the person "An approval request is waiting for your decision, then resume."
+and gave them a Resume button and no way to decide; the runner re-asks rather than proceeding, so
+the pause could not be cleared from the UI at all.
+
+Fixed: the run page renders the decision again. The request's values appear in plain words — the
+value, then the row's own columns — and never the step id, the action name or the target ladder the
+payload also carries (`lib/approvals.ts` drops them). One gold primary button ("Go ahead") and one
+quiet one ("No, stop this row"), the operator id from `/api/v1/operator` in the body, and both
+disabled with the API's own words when that route answers 503.
+
+Also fixed from the review, each with a test:
+
+- **The "next to the button" placement assertion for a run refusal** had been weakened to a
+  presence check; the run actions now carry `.run-action-pause/resume/cancel` and the test asserts
+  the shared container, as PL-015 did.
+- **The `queued` status** was only asserted as a pure function; the page test now renders it.
+- **`POLL_INTERVAL_MS`** was no longer asserted anywhere; now it is.
+- **An already-finished run still polled once, 2 s after load** — a real regression, because
+  `pollMs` started at 2000. It now starts at `null` and becomes 2000 only once the payload says the
+  run is open.
+- **The injection test** was deleted with the old page; a case for a hostile `record_key`/`reason`
+  is back.
+- **An unknown `/api/...` path answered the app shell at 200** instead of the API's own JSON 404,
+  so a caller parsing JSON waited on a request that had failed. The SPA fallback now serves the page
+  only for a path that is neither an asset nor under `api/`.
+- **The fix for that also caught a Windows-only bug in itself**: Starlette normalises the mount's
+  path with `os.path.normpath`, so on this machine the separators are backslashes and the `api/`
+  prefix test silently never matched. It is normalised back, so it behaves the same here and on the
+  deployment. This one is worth T1's attention precisely because it passed on neither side by
+  accident: it was the test that caught it.
+
+The reviewer's "checked and sound" list, which I re-verified: `counts.needs_help` really is the
+length of the `/needs-help` response (one read, one filter, one order); the new SQL matches
+`internal/docs/sql-patterns.md` and the real schema; every page guards division by zero; every
+dependency in `apps/web/package.json` is an exact pin with no Tailwind and no component library; the
+hub's new route changes no frame, socket, token check or protocol constant; and nothing touched the
+ledger state machine, the runner, or the re-queue safety check.
+
+## The safety rule (requirement 6)
+
+Unchanged and enforced on this branch. `needsHelpActions.ts` is PL-015's gate plus a stricter
+one: a `commit_attempted` row stays disabled until the box is ticked **and** the API has named an
+operator, `actionBody` throws rather than ever omitting `destination_checked_by` for such a row, and
+the page computes the gate and the body from the same `confirmed[record_id]` read in the same
+render, so a tick cannot go stale between the two. The API and the database trigger remain the
+backstop; no line of either changed.
+
+## Things worth recording
+
+- **Four builders, disjoint files, all on deepseek-flash.** Builder A (stack, tokens, shell, router,
+  shared modules, serving, hub route) landed first; B (Home + the API module) followed; C (Tasks,
+  Runs, the step sentences) ran third and **hit its model-step budget before reporting** — its work
+  was on disk, so I verified and salvaged it myself rather than re-running the lane; D (Needs help +
+  the engine-word test) landed last. Two spawns of B were refused for write-scope contention with a
+  sibling that held `.`; the second B and all of C and D were given a bounded wall clock, and the
+  shared contract (`.cache/pl023-plan.md`) is what let the lanes stay disjoint.
+- **C's budget failure is why the phone-width work is mine.** Nothing in the plan said to measure at
+  phone width; I did it with a browser, measured the document scroll width at 400 and 360 px on
+  every route, and found the task, run and home tables pushing the document to 480 px. The fix hides
+  the column that is only context (when a task last ran, when a run started) and keeps the result,
+  and lets a long value break rather than widen the page. Screenshots at 1280 and 400 for Home,
+  Tasks, Runs, one run, one task and Needs help are in `.cache/pl023-serve/`.
+- **`.cache/pl023-plan.md` is the contract the four builders worked to** — the frozen vocabulary
+  table, the module signatures, the API response shapes and the page copy. It is scratch (`.cache/`
+  is gitignored), so if T1 wants it kept it must be moved into `internal/`.
+- **`internal/docs/sql-patterns.md` gained one section** for the week's-counts and window-wall-clock
+  shapes, since they name `runs`/`run_records` and the separation rule requires the pattern be
+  recorded before it is used.
+- **Two additive read fields**: `RunClaim.started_at`/`finished_at` (defaulted, so a hand-built
+  `RunClaim` in a test still constructs) and the same two on `RunDetail`. They are the only honest
+  source for a finished run's duration.
+- **The mock's avatar is not reproduced.** It reads `JV`; nothing in this repository knows the
+  operator's name, so the header draws a person outline instead of inventing initials.
+- **`app` on a task is the host, not a product name** — `crm.example.com`, not "Odoo CRM". There is
+  no product-name catalogue in the data yet, so the page shows what it has.
+- No screenshots are committed; the ones above are scratch, as the ticket's acceptance criteria say
+  T1 tests in the browser.
+
+## Scope notes
+
+- The root `docker-compose.yml` is modified in the working tree — `minio/minio:latest` →
+  `cgr.dev/chainguard/minio:latest`. **That change is the owner's, predates this ticket, and was
+  left uncommitted on purpose.** Every commit here adds explicit paths only, so it cannot be swept
+  in.
+- `internal/docs/DECISIONS.md` carries an uncommitted **D-024** (internal tool first, SaaS-ready),
+  and `internal/agent/tickets/PL-026.md`, `internal/agent/tickets/ADM-001.md` and
+  `internal/docs/design/admin-mock.html` are untracked. **None of those are mine**, they are not part
+  of PL-023, and they were left alone. D-023 is committed.
+- `internal/docs/TEST-MOCK/` is untracked and not gitignored, so a careless `git add -A` would commit
+  it. It was left alone and is in no commit here.
+- No ledger, runner, hub-protocol or re-queue-safety change. `services/api/hub.py` gains one
+  read-only route that reads the hub's own registry under its own lock; no frame, socket, token or
+  protocol constant moved.
+- No e2e was run, per the ticket.
+
+## Commits on `pl-023`
+
+1. `docs(tickets): add PL-023 and PL-025 with the design rules and the approved Home mock` — incl. D-023
+2. `feat(web): rebuild apps/web in React with the approved shell, tokens and router`
+3. `feat(api): add the week's home reads, the needs-help set and the saved tasks`
+4. `feat(web): build the Home screen from the week's real data`
+5. `feat(web): add the Tasks and Runs screens and the plain-words step sentences`
+6. `feat(web): add the Needs help screen and the engine-word test`
+7. `fix(web): keep every page inside a 400-pixel screen`
+8. `fix(web): keep the engine's own words off the screen in a refusal`
+9. `fix(api): keep an API miss a JSON 404, and stop polling a finished run`
+
+## What T1 should look at hardest
+
+1. The two review majors above, in the browser: make a 409 happen on `/needs-help` (two tabs on the
+   same row) and confirm the person reads a sentence rather than `run_record … is not parked`; and
+   open a run paused `awaiting_approval` and decide it.
+2. `refusalWords`'s fallback. It is the one place a judgement was made about wording, and the shape
+   list (`is not parked`, `does not exist`, `not the expected state`, `illegal ledger transition`)
+   is a guess at the API's future messages rather than a contract.
+3. The per-state counts the old operator page showed and this one no longer does — a deliberate
+   reading of requirement 5, not an oversight.

From c68703e9de57f6b8df0046cdba6855c0b8f0b630 Mon Sep 17 00:00:00 2001
From: Jayanth Vasupilli <156448548+jayanthvee@users.noreply.github.com>
Date: Thu, 15 Oct 2026 18:49:23 -0700
Subject: [PATCH 11/12] fix(api): count only finished runs against time saved,
 and 404 a bare /api

Review fixes for PL-023: a paused or queued run no longer subtracts its waiting time from the
week's time saved, and /api with no trailing slash is an API miss instead of the page.
---
 internal/agent/reports/PL-023-review.md | 49 +++++++++++++++++++++++++
 packages/ledger/reads.py                | 11 ++++--
 services/api/main.py                    |  3 +-
 tests/api/test_home_api.py              | 39 ++++++++++++++++++++
 tests/api/test_web_serving.py           |  8 ++++
 5 files changed, 105 insertions(+), 5 deletions(-)
 create mode 100644 internal/agent/reports/PL-023-review.md

diff --git a/internal/agent/reports/PL-023-review.md b/internal/agent/reports/PL-023-review.md
new file mode 100644
index 0000000..a2d80be
--- /dev/null
+++ b/internal/agent/reports/PL-023-review.md
@@ -0,0 +1,49 @@
+# PL-023 review (T1)
+
+Branch `pl-023` at `9e9d5b1`, plus T1's fix commit. **Verdict: approved** with the fixes below.
+
+## Gates (T1, on the branch)
+- `npm --prefix apps/web run check`: typecheck clean, 98 tests, build ok.
+- `python -m pytest -q`: 697 passed before T1's fixes; the touched modules pass after them.
+- `ruff check .` and `ruff format --check .`: clean.
+- e2e: see the PR description.
+
+## Scope
+There is no change to the runner, the hub's frames or protocol, the migrations, or any ledger write or
+transition.
+- `packages/ledger/reads.py` is SELECT only.
+- `GET /api/v1/executor/session` is one new read-only, local-only hub route that returns `{"attached": bool}`.
+- The re-queue safety check is untouched, and the needs-help set (`parked`, `failed`) is exactly what the
+  re-queue endpoint accepts.
+
+## Fixed by T1
+1. **Major: time saved subtracted waiting time.** `_WINDOW_RUN_SECONDS` summed `coalesce(finished_at, now()) -
+   coalesce(started_at, created_at)` over every run, open or not.
+   - So a run paused over a weekend for an approval, or a queued run no worker had claimed, subtracted days of
+     wall clock, and the week's time saved read 0.
+   - Now only runs that finished inside the window count, start to finish. This also lines the run-time window up
+     with the rows' window.
+   - Two tests were added: an open run (paused, or queued) subtracts nothing; a finished 10-minute run subtracts 10
+     minutes.
+2. **Minor: bare `/api` served the page.** The SPA fallback only tested the `api/` prefix. `/api` now 404s like
+   any API miss, with a test.
+
+## Browser check (T1)
+Served by `services/api` against the dev database with synthetic rows. Home, Needs help, Tasks and Runs render
+real data, and the vocabulary is plain. The only console errors were 503s from a first start without
+`DATABASE_URL`, which is expected.
+
+## Follow-ups (not blocking)
+- **The Needs help page shows a developer message** when `PROCESSLENS_OPERATOR_ID` is unset: "The API has no
+  operator identity … Set PROCESSLENS_OPERATOR_ID and restart the API". It is true but not plain. Sign-in (the
+  Railway ticket) removes the case. Until then, reword it to "You can look, but can't change anything here
+  until ProcessLens knows who you are", and keep the variable name in the console.
+- **"Running now" includes queued runs** under the Live marker. Show queued runs as "Waiting to start", or leave
+  them out of that panel.
+- A client route whose last segment contains a dot (`/tasks/v1.2`) 404s on refresh, because of the
+  `Path(...).suffix` asset test. Today's routes use UUIDs, so this is harmless for now.
+- `test_web_serving.py` skips itself when `apps/web/dist` isn't built. CI must build the web app before
+  pytest, or those checks never run.
+- `week_counts` scans `run_record_transitions` with no index on `at`, and joins `run_records` when the
+  transition row already carries `tenant_id`. This is performance only; add the index before 500-row batches
+  pile up.
diff --git a/packages/ledger/reads.py b/packages/ledger/reads.py
index 56dbe03..cf859c3 100644
--- a/packages/ledger/reads.py
+++ b/packages/ledger/reads.py
@@ -157,15 +157,18 @@ def list_open_approvals(conn: psycopg.Connection, run_id: uuid.UUID) -> list[App
   AND (%(tenant)s::uuid IS NULL OR rr.tenant_id = %(tenant)s)
 """
 
-# The wall clock the window's runs took: an unfinished run is counted up to now, and a run that a
-# worker never claimed falls back to its creation time.
+# The wall clock of the runs that finished inside the window, from start to finish. An open run
+# (queued, running or paused) is left out until it finishes, so a run paused over a weekend for an
+# approval does not wipe out the week's time saved while it waits.
 _WINDOW_RUN_SECONDS = """
 SELECT coalesce(
-         sum(extract(epoch FROM (coalesce(finished_at, now()) - coalesce(started_at, created_at)))),
+         sum(extract(epoch FROM (finished_at - started_at))),
          0
        )::double precision AS seconds
 FROM runs
-WHERE coalesce(started_at, created_at) >= now() - make_interval(days => %(days)s)
+WHERE finished_at IS NOT NULL
+  AND started_at IS NOT NULL
+  AND finished_at >= now() - make_interval(days => %(days)s)
   AND (%(tenant)s::uuid IS NULL OR tenant_id = %(tenant)s)
 """
 
diff --git a/services/api/main.py b/services/api/main.py
index 708d361..d55d6e1 100644
--- a/services/api/main.py
+++ b/services/api/main.py
@@ -146,7 +146,8 @@ async def get_response(self, path: str, scope: MutableMapping[str, Any]) -> Resp
         past it on this machine and not on the deployment.
         """
         relative = path.replace("\\", "/").lstrip("/")
-        if relative.startswith(self.API_PREFIX) or Path(relative).suffix:
+        is_api = relative == self.API_PREFIX.rstrip("/") or relative.startswith(self.API_PREFIX)
+        if is_api or Path(relative).suffix:
             return await super().get_response(path, scope)
         try:
             response = await super().get_response(path, scope)
diff --git a/tests/api/test_home_api.py b/tests/api/test_home_api.py
index 519afb1..76dc8d1 100644
--- a/tests/api/test_home_api.py
+++ b/tests/api/test_home_api.py
@@ -136,6 +136,45 @@ def test_the_minutes_saved_are_clamped_at_zero(
     assert body["minutes_saved"] == 0
 
 
+def test_an_open_run_does_not_eat_the_time_saved(
+    connected: TestClient, conn: psycopg.Connection, ledger: Ledger
+) -> None:
+    """A run paused for two days, or queued and never claimed, subtracts nothing until it ends."""
+    ledger.seed_records(10, state="verified")
+    paused = ledger.new_run()
+    queued = ledger.new_run()
+    conn.execute(
+        "UPDATE runs SET status = 'paused', created_at = now() - interval '2 days', "
+        "started_at = now() - interval '2 days' WHERE id = %s",
+        (paused.id,),
+    )
+    conn.execute(
+        "UPDATE runs SET created_at = now() - interval '2 days' WHERE id = %s", (queued.id,)
+    )
+
+    body = home_body(connected, ledger)
+
+    assert body["counts"]["done"] == 10
+    assert body["minutes_saved"] == 30
+
+
+def test_a_finished_run_subtracts_its_start_to_finish_time(
+    connected: TestClient, conn: psycopg.Connection, ledger: Ledger
+) -> None:
+    """Ten rows are thirty minutes by hand; a run that took ten minutes saved twenty."""
+    ledger.seed_records(10, state="verified")
+    run = ledger.new_run()
+    conn.execute(
+        "UPDATE runs SET status = 'completed', started_at = now() - interval '10 minutes', "
+        "finished_at = now() WHERE id = %s",
+        (run.id,),
+    )
+
+    body = home_body(connected, ledger)
+
+    assert body["minutes_saved"] == 20
+
+
 def test_the_needs_help_panel_is_the_newest_three_in_order(
     connected: TestClient, ledger: Ledger
 ) -> None:
diff --git a/tests/api/test_web_serving.py b/tests/api/test_web_serving.py
index 38a61f5..ff6c42c 100644
--- a/tests/api/test_web_serving.py
+++ b/tests/api/test_web_serving.py
@@ -50,3 +50,11 @@ def test_an_unknown_api_path_still_404s_as_json(client: TestClient) -> None:
     assert response.status_code == 404, response.text
     assert response.headers["content-type"].startswith("application/json")
     assert ROOT_ELEMENT not in response.text
+
+
+def test_a_bare_api_path_is_not_the_page(client: TestClient) -> None:
+    """`/api` with no trailing slash is an API miss too, never the page."""
+    response = client.get("/api")
+
+    assert response.status_code == 404, response.text
+    assert ROOT_ELEMENT not in response.text

From 8734a4e0c362c4d7a53372ed438cffe8a35d1fb8 Mon Sep 17 00:00:00 2001
From: Jayanth Vasupilli <156448548+jayanthvee@users.noreply.github.com>
Date: Thu, 15 Oct 2026 18:49:24 -0700
Subject: [PATCH 12/12] docs(tickets): add PL-026 and ADM-001 for the modular
 admin panel, with D-024 and D-025

---
 internal/agent/tickets/ADM-001.md    | 203 +++++++++++++++++++++
 internal/agent/tickets/PL-026.md     | 103 +++++++++++
 internal/docs/DECISIONS.md           |   2 +
 internal/docs/design/admin-mock.html | 252 +++++++++++++++++++++++++++
 4 files changed, 560 insertions(+)
 create mode 100644 internal/agent/tickets/ADM-001.md
 create mode 100644 internal/agent/tickets/PL-026.md
 create mode 100644 internal/docs/design/admin-mock.html

diff --git a/internal/agent/tickets/ADM-001.md b/internal/agent/tickets/ADM-001.md
new file mode 100644
index 0000000..34bb53f
--- /dev/null
+++ b/internal/agent/tickets/ADM-001.md
@@ -0,0 +1,203 @@
+# ADM-001: The admin panel — the module system, plus Overview, People, Runs, Tasks, AI spend and Activity
+
+Repository: **`process-lens-admin`** (private, cloned next to `process-lens`) · Owner: T2 · Reviewer: T1 ·
+Depends on: PL-026 (merged) · Decisions: D-023, D-024, D-025
+
+This ticket is kept in `process-lens` with every other ticket. T2 works in `../process-lens-admin` and reads this
+file, `../process-lens/internal/docs/DESIGN.md` and `../process-lens/internal/docs/ADMIN-MODULES.md` from the
+sibling clone.
+
+## Who it is for, and what it is for
+One or two people run ProcessLens for the company: an ops lead, IT, or the owner. They are more technical than
+the people teaching tasks, but not developers. The admin panel answers three questions:
+
+1. **Is anything wrong right now?**
+   - Stuck runs.
+   - A pile of rows that need help.
+   - A task that keeps failing.
+   - People on an old Chrome extension.
+
+   And they can stop everything with one button.
+2. **Who can do what?** People, their roles, turning someone's access off, and which extension version each
+   person runs.
+3. **What is it costing, and what is it saving?** AI spend, rows done, and time saved across the company.
+
+The admin panel **never shows row contents**: no spreadsheet values, no document text, no screenshots. It shows
+counts, task names, people and reasons only.
+
+## Modular by design (D-025)
+Every admin feature is a **module**, so a later feature that needs a migration slots in without touching the
+others.
+
+- **A module is two folders and one manifest:**
+  - `api/modules/<id>/`: a FastAPI router, its queries, and `manifest.py`;
+  - `web/src/modules/<id>/`: its pages, and `manifest.ts`.
+- **The manifest declares:**
+  - `id`, its title and its sidebar entries (label, icon, path, order);
+  - `requires`: the `admin_modules` row it needs (for example `core`), or nothing;
+  - `writes`: the tables and columns it writes, documentation checked by a test against the role's grants.
+- **A registry** (`api/registry.py`, `web/src/registry.ts`) loads every manifest.
+  - At API start-up it reads `admin_modules` from the database.
+  - A module whose required row is missing is **not mounted**. Its sidebar entry shows "Needs a ProcessLens
+    update" and its page explains that in one sentence. The panel never crashes on an older schema.
+  - `GET /api/modules` tells the web app which modules are on.
+- **The shell knows nothing about any module.** The sidebar, routes and Overview "needs a look" items all come
+  from the registry. Each module may contribute Overview items through a `needs_a_look()` hook.
+- **A new module that needs schema** is always a pair of tickets (`ADMIN-MODULES.md`):
+  - a PL ticket: the migration in `process-lens`, its `admin_modules` row, and its grants;
+  - an ADM ticket: the module here.
+- `scripts/new_module.py <id>` scaffolds both folders and the manifests.
+
+**The modules in this ticket:** `overview`, `people`, `runs`, `tasks`, `ai_spend` and `activity`.
+- `people`, `runs`, `overview` (its freeze switch) and `activity` require `core`.
+- `tasks` and `ai_spend` require nothing; they only read existing tables.
+
+## The look: the same design language, in dark fog
+Follow `DESIGN.md` §1–§3 and §5–§7 exactly: Public Sans, the vocabulary table, panels, rows and motion. The one
+difference is that the admin panel is **dark only**, so an admin always knows which app they are in.
+
+- **The approved mock** is `internal/docs/design/admin-mock.html` in `process-lens`. Port its tokens and
+  structure. Ignore its AI budget bar: budgets were cut.
+- **Tokens:** the same names as the main app's `tokens.css`, with the dark values from the mock:
+  - fog `#121614` / `#191d1b` / `#232825`;
+  - glass is white at 4–8%;
+  - ink `#e7eae7`;
+  - gold stays the one accent;
+  - state colors `--ok`, `--help` and `--live`, plus **`--stop`**, used for "Pause everything" only.
+- **"Pause everything"** is the only red thing on any screen. It is an outlined button, and always asks for
+  confirmation in the page.
+
+## Requirements
+1. **The repository.**
+   - Layout:
+     - `web/`: React 18, React Router, TypeScript and Vite. Plain CSS, `@fontsource/public-sans`. No Tailwind,
+       no component library.
+     - `api/`: Python 3.12, FastAPI, psycopg 3.
+     - `scripts/`.
+     - `AGENTS.md`: the `process-lens` constitution, adapted. Same git rules and attribution ban; D-017 does not
+       apply; the database and module rules here are added.
+     - `README.md`, `.env.example` and `.gitignore`.
+   - Pin every dependency to an exact version.
+   - The gates are `npm --prefix web run check` (typecheck, test, build), `python -m pytest -q`, and
+     `ruff check .` plus `ruff format --check .`.
+2. **The database rules** (mandatory: D-023 and PL-026).
+   - Connect with `ADMIN_DATABASE_URL`, a login in the `processlens_admin` role. **Never run migrations**, and
+     there is no `db/` folder in this repo.
+   - SQL writes go only to:
+     - `admin_audit`;
+     - `users.role` and `users.deactivated_at`.
+   - **Everything that affects runs, or the minimum extension version, goes through the ProcessLens API**
+     (`PROCESSLENS_API_URL`, with the `PROCESSLENS_ADMIN_TOKEN` header): pause, cancel, freeze, unfreeze, and
+     setting the minimum version.
+   - Every admin action writes one `admin_audit` row, with its `module`. A direct SQL write and its audit row go
+     in one transaction.
+   - Every query filters by the signed-in admin's `tenant_id` (SaaS-ready, D-024). Follow
+     `../process-lens/internal/docs/sql-patterns.md`.
+3. **Sign-in, behind one interface** (`api/auth.py`: `current_admin() -> Admin`).
+   - Now: a local dev provider. It reads `ADMIN_DEV_EMAIL`, looks the user up, and refuses anyone whose role is
+     not `owner` or who is deactivated.
+   - The API binds to `127.0.0.1` only.
+   - SSO replaces the provider in the Railway ticket, with no module changes.
+4. **The shell.**
+   - The sidebar, 216 px, frosted dark, built from the registry. At the bottom: Settings ("Coming soon") and
+     "Back to ProcessLens".
+   - The header: page title, then the company name and the avatar.
+   - **When runs are frozen**, a full-width bar shows on every page: "All runs are paused. Paused by Jay at
+     14:02." with **Let runs start again**.
+5. **`overview`** (`/`), as in the mock.
+   - **Headline:** "All quiet." / "2 runs going. Nothing needs you." / "2 runs going. 1 thing needs a look."
+   - **Pause everything,** with the confirmation from the mock.
+   - **Three figures** in one strip:
+     - rows done this week;
+     - **time saved this week** (the gold figure, the same formula as PL-023: finished runs only);
+     - AI spend this month (a plain dollar figure, no budget).
+   - **Needs a look:** the items every mounted module contributes, each with one action.
+     - `runs`: a run whose heartbeat is more than 2 minutes old ("Stopped responding"); a run with 10 or more rows
+       needing help.
+     - `tasks`: a task whose last 3 runs ended with more rows not working than done ("Keeps failing").
+     - `people`: people below the minimum extension version ("3 people need to update the Chrome extension"); a
+       deactivated person with an open run.
+   - **Running now:** person, task, live progress (poll every 5 s), and **Pause**.
+6. **`people`** (`/people`).
+   - The table:
+     - name and email;
+     - role;
+     - **Chrome extension version**, with "Out of date" in `--help` when it is below the minimum, and "Not seen
+       yet" when there is no report;
+     - last active;
+     - one action.
+   - Change a role with a select that has one plain line per role:
+     - Owner: everything, including this panel;
+     - Builder: teaches and runs tasks;
+     - Reviewer: fixes rows that need help, and approves;
+     - Viewer: can look, can't change anything.
+   - **Turn off access** / **Turn access back on**, with a confirmation. An owner can't demote or turn off
+     themselves, or the last owner.
+   - **"Minimum extension version"**, a small form above the table. It shows how many people it would block
+     before saving.
+   - Show "People join by signing in with your company account" instead of an invite button.
+7. **`runs`** (`/runs`): every run across the company.
+   - The columns: task, person, started, status, "11 of 20 done", and **Pause** or **Cancel** where allowed.
+   - Two filters: person and status.
+   - Clicking a run opens the main app's run page in a new tab.
+8. **`tasks`** (`/tasks`), read-only.
+   - The columns: task, who taught it, the apps it uses, runs in the last 30 days, and the share of rows done.
+9. **`ai_spend`** (`/ai`).
+   - The month's total.
+   - A per-day bar chart in `--gold`, drawn to scale, with an axis.
+   - "Where it went": a table by feature, in plain names, with calls, spend and share:
+     - `normalize_fields` → **Cleaning spreadsheet values**;
+     - `extract_document` → **Reading documents**;
+     - `propose_repair` → **Fixing broken steps**;
+     - anything else → **Other**.
+   - The model name shows only in a hover title. The source is `ai_calls`.
+10. **`activity`** (`/activity`).
+    - One list, newest first, paged by 50, merging:
+      - `admin_audit`;
+      - `approvals`;
+      - runs started and finished;
+      - re-queues.
+    - Each line is a plain sentence, a person and a time.
+    - Filter by person.
+    - **Export CSV** (filtered rows; no row contents).
+11. **No engine words** on screen: the same forbidden-word vitest as PL-023 requirement 7, over every module's
+    pages.
+12. **Motion and accessibility** as in DESIGN.md §7: visible focus on dark, usable at 400 px wide.
+
+## Later (not in this ticket)
+- **Approval rules** (low priority): a new or changed task needs a reviewer before its first full run. This is a
+  module plus a PL migration.
+- Settings: screenshot retention, and which AI providers may see personal data.
+- Invites and SSO, a health page, the Railway deploy, and the cross-company operator view (SaaS).
+
+## Acceptance criteria
+- [ ] All gates pass in `process-lens-admin`.
+- [ ] API tests run against the Docker Postgres with `process-lens` migrations applied, connected **as
+  `processlens_admin`**. They prove:
+  - a write to `runs` is refused;
+  - every admin action leaves one `admin_audit` row;
+  - another tenant's rows never appear;
+  - **with the `core` row deleted from `admin_modules`** (in a test transaction), the panel starts, the `core`
+    modules are unmounted and show "Needs a ProcessLens update", and `tasks` and `ai_spend` still work;
+  - every manifest's `writes` matches the role's actual column grants.
+- [ ] No row values appear in any API response. A test asserts the response keys.
+- [ ] `scripts/new_module.py demo` produces a module that mounts, then is deleted.
+- [ ] The report goes in `process-lens/internal/agent/reports/ADM-001.md`, committed on a `process-lens` branch
+  `adm-001-report`. It lists each module with its data source. **T1 tests in the browser.**
+
+## T2 operating rules for this ticket
+- **A separate CodeWhale session**, opened in `process-lens-admin`. Don't edit `process-lens` except the report.
+- Sub-agents run on deepseek-flash only. Builders use thinking high and `max_steps` 80; the coordinator stays
+  low.
+- **Split the builders by disjoint files:**
+  - builder A: the scaffold, tokens, shell, auth and the module registry, plus `new_module.py` (goes first);
+  - builder B: `overview` and `people`;
+  - builder C: `runs`, `tasks` and `activity`;
+  - builder D: `ai_spend`, and the registry and grants tests.
+- No e2e runs and no plan stop. Stop only for:
+  - a need to write any table not listed in requirement 2;
+  - a need for a schema change (that is a PL ticket);
+  - three identical failures.
+- On Windows, never use `2>&1` or the PowerShell `&` call operator. Scratch files go only under `.cache/`.
+- Use conventional commits with no AI attribution. Never push to `main`; work on branch `adm-001`, push it, and
+  stop for T1.
diff --git a/internal/agent/tickets/PL-026.md b/internal/agent/tickets/PL-026.md
new file mode 100644
index 0000000..aeb32a8
--- /dev/null
+++ b/internal/agent/tickets/PL-026.md
@@ -0,0 +1,103 @@
+# PL-026: What the admin panel needs from ProcessLens
+
+Owner: T2 · Reviewer: T1 · Depends on: PL-023 (merged) · Phase: D · **Critical (touches the runner): T1 writes
+break-it tests before merge** · Decisions: D-023, D-025
+
+## Description
+The admin panel lives in its own repository (D-023) and is built from modules (D-025). A module that needs the
+schema to change gets its migration here, in this repository, because this repository owns the schema and the
+runner. This ticket adds the first admin module migration and the product behaviour behind it:
+
+- the admin module registry;
+- a log of admin actions;
+- the database role the admin panel connects as;
+- a "pause everything" switch the runner obeys;
+- turning off a person's access;
+- the Chrome extension version check.
+
+## Requirements
+1. **Migration `db/migrations/0004_admin_core.sql`**, the `core` admin module.
+   - `admin_modules`: one row per admin module this schema supports. Columns: `id text PRIMARY KEY`,
+     `migration text NOT NULL`, `added_at`. This migration inserts the row `('core', '0004_admin_core.sql')`.
+     Every later admin-module migration inserts its own row in the same file. The admin panel reads this table
+     to decide which modules to switch on (D-025).
+   - New columns:
+     - `tenants.runs_frozen_at timestamptz` and `tenants.runs_frozen_by uuid REFERENCES users(id)`;
+     - `tenants.min_extension_version text` (null means any version);
+     - `users.deactivated_at timestamptz`.
+   - `extension_reports`: the version each person's extension last reported. Columns: `user_id` (primary key),
+     `tenant_id`, `version`, `reported_at`.
+   - `admin_audit`, append-only through the `forbid_mutation()` trigger, like `approvals`:
+     - columns: `id`, `tenant_id`, `actor_user_id`, `module` (text), `action` (text), `target` (text), `detail`
+       (jsonb), `at`;
+     - actions in this migration: `freeze_runs`, `unfreeze_runs`, `change_role`, `deactivate_user`,
+       `reactivate_user`, `pause_run`, `cancel_run`, `set_min_extension_version`.
+   - The role `processlens_admin` (NOLOGIN; the deploy creates a login that inherits it):
+     - `SELECT` on every table;
+     - `INSERT` on `admin_audit`;
+     - `UPDATE (role, deactivated_at)` on `users`;
+     - `UPDATE (min_extension_version)` on `tenants`;
+     - **nothing else.** It cannot touch `runs`, `run_records`, `committed_keys` or `jobs`.
+     - Every later admin-module migration grants only the columns its module writes, in the same file.
+2. **The freeze switch: the API and the runner.**
+   - `POST /api/v1/admin/freeze` and `POST /api/v1/admin/unfreeze` set and clear `runs_frozen_at`. Each writes an
+     `admin_audit` row in the same transaction.
+   - When frozen:
+     - `POST /runs` and `/runs/{id}/resume` return 409 with "Runs are paused by an admin".
+     - The runner checks the flag **at the same step boundary where it checks `cancel_requested_at`**. It pauses
+       the run there with `pause_reason = 'admin_freeze'`, after reconciling any record in the commit window.
+       **Never stop between `submitting` and `verified`.**
+   - Unfreeze does not resume runs. Each run is resumed by a person.
+3. **The extension version check.** No change to the hub protocol or its frames.
+   - The extension reports its manifest version to a new `POST /api/v1/executor/version`:
+     - each time the command session reaches `ready`;
+     - the API stores it in `extension_reports` against the operator.
+     - The extension change is this one call in the service worker, plus its unit test. Nothing else in the
+       extension changes.
+   - `POST /api/v1/admin/min-extension-version` sets or clears the minimum, with an audit row.
+   - While the reported version is below the minimum:
+     - `POST /runs` and `/runs/{id}/resume` return 409 with "Update the ProcessLens Chrome extension to version X
+       or newer";
+     - **runs already going are not interrupted.**
+   - Compare versions numerically, part by part: `1.10.0` is newer than `1.9.2`.
+4. **A deactivated user** can't start, resume or approve anything (403). Their open runs keep their state.
+5. **The web app** (PL-023) shows banners:
+   - when frozen: "An admin paused all runs. Nothing new will start." The Run buttons are disabled.
+   - when the extension is too old: "Your Chrome extension is out of date. Update it to keep running tasks."
+6. **The admin endpoints.** These, plus the existing pause and cancel, are the **only** write paths the admin
+   panel uses for anything that affects runs. Until sign-in lands with the Railway ticket, they accept requests
+   only from `127.0.0.1`, with a shared `PROCESSLENS_ADMIN_TOKEN` header (read from the environment, never
+   committed).
+7. **`internal/docs/ADMIN-MODULES.md`**, one page, explaining how to add an admin module that needs schema:
+   - the PL migration: its tables or columns, its `admin_modules` row, and its grants;
+   - the ADM ticket: the module folder and its manifest, naming that migration.
+
+## Out of scope
+The admin panel itself (ADM-001, in `process-lens-admin`), sign-in and SSO, and Railway.
+
+## Acceptance criteria
+- [ ] Gates:
+  - `python -m pytest -q`
+  - `ruff check .` and `ruff format --check .`
+  - `npm --prefix apps/web run check`
+  - `npm --prefix apps/extension run check`
+- [ ] Tests:
+  - freeze during a run pauses it at the next boundary;
+  - a record in `submitting` at freeze time is reconciled, not abandoned;
+  - starting and resuming a run return 409 while frozen, and while the extension is below the minimum;
+  - a run already going is not stopped by a new minimum;
+  - version compare: `1.10.0` > `1.9.2`, `2.0` = `2.0.0`, and a malformed version is refused at 422;
+  - the `processlens_admin` role is refused an `UPDATE` on `runs` and on `run_records`;
+  - `admin_audit` rejects `UPDATE` and `DELETE`;
+  - `admin_modules` contains `core` after migration.
+- [ ] T1 runs the e2e suite.
+
+## T2 operating rules for this ticket
+- Sub-agents run on deepseek-flash only. Builders use thinking high and `max_steps` 80; the coordinator stays
+  low.
+- No e2e runs. **Stop and report before changing:**
+  - anything in the runner beyond the one boundary check;
+  - any hub frame or protocol.
+- On Windows, never use `2>&1` or the `&` call operator. Scratch files go only under `.cache/` or `.data/`.
+- Use conventional commits with no AI attribution. Never commit the root `docker-compose.yml` or
+  `internal/docs/TEST-MOCK/`. Push the branch and stop for T1.
diff --git a/internal/docs/DECISIONS.md b/internal/docs/DECISIONS.md
index ea68639..b8bc681 100644
--- a/internal/docs/DECISIONS.md
+++ b/internal/docs/DECISIONS.md
@@ -28,3 +28,5 @@ Entries are never edited after acceptance; a later entry supersedes an earlier o
 | D-021 | Hosting: Railway runs the API, the workers, Postgres and the web app | The choice was Vercel or Railway. Vercel cannot hold the hub's WebSocket connection and cannot run long-lived workers, and those are the two constraints this system actually has; Railway runs both, with a managed Postgres beside them in the same project | Accepted (owner) | 2026-10-15 |
 | D-022 | Test targets: real open-source apps run locally in Docker (Odoo 18 Community and Twenty CRM, PL-022) replace the hand-built mock sites as the main targets for recording and replay. The mocks stay for unit-level fixture tests | Pages we wrote ourselves contain only the bugs we already thought of. Real software brings autocompletes, inline editing, command menus and duplicate checks that nobody here wrote, so replay is tested against software we do not control. The mocks stay because unit and fixture tests need a target that cannot drift under them | Accepted (owner) | 2026-10-15 |
 | D-023 | The admin panel lives in its own repository (owner's mandate), sharing the ProcessLens database through a separate, least-privilege Postgres role. Schema and migrations stay owned by this repo; the admin repo never runs migrations. Supersedes D-018 for the admin panel only | Owner's mandate. The admin panel is a separate deliverable with its own access surface, while the schema and its migrations stay in exactly one place and the admin repository reaches the database only through a role that can do what the panel needs and nothing more | Accepted (owner) | 2026-10-15 |
+| D-024 | Internal tool first, SaaS-ready: one company uses ProcessLens now, but nothing assumes a single company. Every table keeps its `tenant_id` and every query filters by it; sign-in sits behind one interface (company SSO now, sign-up later); usage (rows done, AI spend) is metered from day one; the landing page stays in the backlog for the SaaS phase. The admin panel (D-023) changes run state only through the ProcessLens API, never by writing ledger tables | Owner's call: ship an internal tool this week without closing the door on selling it. These choices cost almost nothing now and are expensive to retrofit; routing admin actions through the API keeps the ledger's invariants in one place | Accepted (owner) | 2026-10-15 |
+| D-025 | The admin panel is built from modules. Each module is an API folder and a web folder with a manifest that names the `admin_modules` row it needs and the columns it writes; a registry mounts only the modules whose row the database has, and the shell knows no module by name. A module that needs schema is a pair of tickets: a PL migration in this repository (its tables, its `admin_modules` row and its column grants to `processlens_admin`) and an ADM ticket for the module | Owner's call: admin features that need a migration must slot in without touching the others. Migrations stay in one repository (D-023), the admin panel keeps working against an older schema, and each module's write access is granted column by column | Accepted (owner) | 2026-10-15 |
diff --git a/internal/docs/design/admin-mock.html b/internal/docs/design/admin-mock.html
new file mode 100644
index 0000000..03fbe58
--- /dev/null
+++ b/internal/docs/design/admin-mock.html
@@ -0,0 +1,252 @@
+<title>ProcessLens Admin Mock</title>
+<meta name="claude:viewport-fit-sides" content="cover">
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Public+Sans:wght@300;400;500;600&display=swap">
+<style>
+/* Layout: the main app's shell and rhythm, inverted to a dark fog so an admin always knows where they are.
+   header -> headline + one stop button -> one strip of three figures -> two panels (needs a look | running now).
+   Dark only, by design. Gold stays the one accent; red appears only on "Pause everything". */
+:root {
+  color-scheme: dark;
+  --fog-1: #121614; --fog-2: #191d1b; --fog-3: #232825; --fog-warm: #2a2a22;
+  --glass: rgba(255,255,255,.045); --glass-line: rgba(255,255,255,.08); --glass-strong: rgba(255,255,255,.085);
+  --ink: #e7eae7; --ink-2: #a7aeaa; --muted: #747c78; --hair: rgba(255,255,255,.065); --hair-2: rgba(255,255,255,.12);
+  --gold: #d6b064; --gold-deep: #e2c27c; --gold-soft: rgba(214,176,100,.08); --gold-line: rgba(214,176,100,.28);
+  --primary-a: #d9b663; --primary-b: #c59a3f; --on-primary: #2b2210;
+  --ok: #7cbf94; --help: #e39469; --live: #dcb866; --stop: #e57361;
+  --font: "Public Sans", "Helvetica Neue", Arial, sans-serif;
+}
+
+* { box-sizing: border-box; }
+html, body { min-height: 100%; }
+body {
+  margin: 0; color: var(--ink); font: 14.5px/1.5 var(--font); -webkit-font-smoothing: antialiased;
+  background:
+    radial-gradient(1100px 520px at 12% -12%, var(--fog-3) 0%, transparent 62%),
+    radial-gradient(900px 600px at 100% 0%, var(--fog-warm) 0%, transparent 58%),
+    radial-gradient(1000px 640px at 105% 110%, var(--fog-3) 0%, transparent 60%),
+    linear-gradient(180deg, var(--fog-2), var(--fog-1));
+  background-attachment: fixed; background-color: var(--fog-1);
+}
+:focus-visible { outline: 2px solid var(--ink-2); outline-offset: 2px; border-radius: 6px; }
+svg.i { width: 16px; height: 16px; flex: none; fill: none; stroke: currentColor; stroke-width: 1.5; stroke-linecap: round; stroke-linejoin: round; }
+
+.app { display: grid; grid-template-columns: 216px minmax(0, 1fr); min-height: 100vh; }
+
+.side { position: sticky; top: 0; height: 100vh; padding: 16px 12px; display: flex; flex-direction: column; gap: 22px;
+  background: rgba(10,13,12,.55); backdrop-filter: blur(18px); -webkit-backdrop-filter: blur(18px); border-right: 1px solid var(--glass-line); }
+.logo { display: flex; align-items: center; gap: 9px; font-weight: 600; font-size: 15px; padding: 2px 8px; }
+.logo svg { width: 21px; height: 21px; }
+.logo small { font-weight: 400; color: var(--muted); font-size: 13px; }
+.nav { display: grid; gap: 2px; }
+.nav a { display: flex; align-items: center; gap: 10px; padding: 8px 10px; border-radius: 8px; color: var(--ink-2); text-decoration: none; font-weight: 500; }
+.nav a:hover { background: var(--hair); color: var(--ink); }
+.nav a.on { background: var(--glass-strong); color: var(--ink); box-shadow: inset 0 0 0 1px var(--hair-2); }
+.side-foot { margin-top: auto; display: grid; gap: 2px; }
+
+main { min-width: 0; padding-block: 16px 64px; padding-left: max(clamp(16px, 3vw, 40px), env(safe-area-inset-left, 0px)); padding-right: max(clamp(16px, 3vw, 40px), env(safe-area-inset-right, 0px)); display: grid; gap: 30px; align-content: start; max-width: 1180px; }
+.head { display: flex; align-items: center; gap: 12px; min-height: 44px; flex-wrap: wrap; }
+.head h2 { margin: 0; font-size: 15px; font-weight: 600; }
+.org { margin-left: auto; color: var(--ink-2); font-size: 13.5px; }
+.avatar { width: 32px; height: 32px; border-radius: 50%; background: var(--glass-strong); border: 1px solid var(--hair-2); display: grid; place-items: center; font-size: 12px; font-weight: 600; }
+
+.btn { display: inline-flex; align-items: center; gap: 8px; font: 500 14px var(--font); border-radius: 9px; padding: 9px 14px; cursor: pointer; border: 1px solid transparent; text-decoration: none; white-space: nowrap; transition: transform .15s ease, border-color .15s ease, background-color .15s ease; color: var(--ink); background: none; }
+.btn.quiet { background: var(--glass-strong); border-color: var(--hair-2); padding: 7px 12px; font-size: 13.5px; }
+.btn.quiet:hover { border-color: var(--ink-2); }
+.btn.primary { background: linear-gradient(180deg, var(--primary-a), var(--primary-b)); color: var(--on-primary); box-shadow: inset 0 1px 0 rgba(255,255,255,.3), 0 8px 18px -10px rgba(0,0,0,.6); }
+.btn.primary:hover { transform: translateY(-1px); }
+.btn.stop { color: var(--stop); border-color: color-mix(in srgb, var(--stop) 55%, transparent); }
+.btn.stop:hover { background: color-mix(in srgb, var(--stop) 10%, transparent); border-color: var(--stop); }
+.btn.stop.solid { background: color-mix(in srgb, var(--stop) 16%, transparent); }
+
+.hero { display: flex; justify-content: space-between; align-items: flex-end; gap: 24px; flex-wrap: wrap; }
+.big { margin: 6px 0 0; font-size: clamp(34px, 4.2vw, 52px); font-weight: 300; letter-spacing: -0.04em; line-height: 1.04; text-wrap: balance; }
+.big span { color: var(--muted); }
+.lede { margin: 12px 0 0; color: var(--ink-2); font-size: 15.5px; }
+
+.confirm { display: grid; gap: 12px; padding: 16px 20px; border-radius: 14px; border: 1px solid color-mix(in srgb, var(--stop) 40%, transparent); background: color-mix(in srgb, var(--stop) 7%, transparent); max-width: 760px; }
+.confirm p { margin: 0; color: var(--ink); }
+.confirm .acts { display: flex; gap: 10px; flex-wrap: wrap; }
+
+.frozen { display: flex; align-items: center; gap: 14px; flex-wrap: wrap; padding: 12px 16px; border-radius: 12px; border: 1px solid color-mix(in srgb, var(--stop) 40%, transparent); background: color-mix(in srgb, var(--stop) 9%, transparent); }
+.frozen b { font-weight: 600; }
+.frozen span { color: var(--ink-2); }
+.frozen .btn { margin-left: auto; }
+
+.panel { background: var(--glass); backdrop-filter: blur(18px); -webkit-backdrop-filter: blur(18px); border: 1px solid var(--glass-line); border-radius: 14px; box-shadow: 0 18px 40px -30px rgba(0,0,0,.8); min-width: 0; }
+.panel-h { display: flex; align-items: center; justify-content: space-between; gap: 12px; padding: 15px 20px 6px; }
+.panel-h h3 { margin: 0; font-size: 15px; font-weight: 600; }
+.panel-h a { color: var(--ink-2); font-size: 13.5px; text-decoration: none; }
+.panel-h a:hover { color: var(--ink); }
+.two { display: grid; grid-template-columns: minmax(0, 1.2fr) minmax(0, 1fr); gap: 18px; }
+
+/* the three figures share one strip; time saved carries the gold */
+.figs { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); }
+.fig { padding: 18px 22px 20px; display: grid; gap: 4px; align-content: start; border-left: 1px solid var(--hair); }
+.fig:first-child { border-left: 0; }
+.fig b { font-size: clamp(28px, 3vw, 38px); font-weight: 300; letter-spacing: -0.035em; line-height: 1.05; font-variant-numeric: tabular-nums; }
+.fig span { color: var(--ink-2); font-size: 13.5px; }
+.fig small { color: var(--muted); font-size: 12.5px; }
+.fig.gold { background: linear-gradient(180deg, transparent, var(--gold-soft)); }
+.fig.gold b { color: var(--gold-deep); }
+.budget { height: 4px; border-radius: 4px; background: var(--hair-2); overflow: hidden; margin-top: 6px; }
+.budget i { display: block; height: 100%; border-radius: 4px; background: var(--help); }
+
+.rows { list-style: none; margin: 0; padding: 0 0 6px; }
+.rows li { display: grid; grid-template-columns: minmax(0,1fr) auto; gap: 14px; align-items: center; padding: 12px 20px; border-top: 1px solid var(--hair); }
+.rows li:first-child { border-top: 0; }
+.rows b { font-weight: 500; }
+.rows p { margin: 1px 0 0; color: var(--ink-2); font-size: 14px; }
+.rows .meta { display: flex; gap: 12px; justify-content: space-between; color: var(--ink-2); font-size: 13.5px; font-variant-numeric: tabular-nums; margin-top: 8px; }
+
+.res { display: inline-flex; align-items: center; gap: 7px; font-size: 13px; font-weight: 500; }
+.res::before { content: ""; width: 7px; height: 7px; border-radius: 50%; background: currentColor; }
+.res.ok { color: var(--ok); } .res.help { color: var(--help); } .res.live { color: var(--live); } .res.idle { color: var(--muted); }
+.res.live::before { animation: pulse 1.8s ease-out infinite; }
+@keyframes pulse { 0% { box-shadow: 0 0 0 0 color-mix(in srgb, var(--live) 55%, transparent); } 70%, 100% { box-shadow: 0 0 0 6px transparent; } }
+
+.track { height: 6px; border-radius: 6px; background: var(--hair-2); overflow: hidden; margin-top: 8px; }
+.track i { display: block; height: 100%; background: linear-gradient(90deg, var(--primary-a), var(--primary-b)); border-radius: 6px; transition: width .9s cubic-bezier(.3,.1,.2,1); }
+.track.stalled i { background: var(--muted); }
+
+.in { animation: blurin .85s cubic-bezier(.2,.7,.2,1) both; animation-delay: calc(var(--i, 0) * 70ms); }
+@keyframes blurin { from { opacity: 0; filter: blur(10px); transform: translateY(8px); } }
+@media (prefers-reduced-motion: reduce) { .in, .res.live::before { animation: none !important; } .track i { transition: none; } }
+
+@media (max-width: 1040px) { .two { grid-template-columns: minmax(0,1fr); } }
+@media (max-width: 780px) {
+  .app { grid-template-columns: minmax(0,1fr); }
+  .side { position: static; height: auto; flex-direction: row; align-items: center; border-right: 0; border-bottom: 1px solid var(--glass-line); overflow-x: auto; padding-left: max(12px, env(safe-area-inset-left, 0px)); padding-right: max(12px, env(safe-area-inset-right, 0px)); }
+  .side .nav { grid-auto-flow: column; }
+  .side-foot, .org, .logo small { display: none; }
+  .figs { grid-template-columns: minmax(0,1fr); }
+  .fig { border-left: 0; border-top: 1px solid var(--hair); }
+  .fig:first-child { border-top: 0; }
+}
+</style>
+
+<svg width="0" height="0" style="position:absolute" aria-hidden="true">
+  <symbol id="i-over" viewBox="0 0 16 16"><path d="M2.5 13.5h11"/><path d="M4 11V7.5M8 11V4M12 11V6"/></symbol>
+  <symbol id="i-people" viewBox="0 0 16 16"><circle cx="6" cy="5.5" r="2.3"/><path d="M2 13c.5-2.2 2.1-3.4 4-3.4s3.5 1.2 4 3.4"/><path d="M10.6 3.4a2.2 2.2 0 0 1 0 4.2M11.8 9.9c1.2.4 2 1.4 2.3 3.1"/></symbol>
+  <symbol id="i-hist" viewBox="0 0 16 16"><path d="M2.8 8a5.2 5.2 0 1 0 1.5-3.7"/><path d="M2.5 2.8v2.4h2.4M8 5.2V8l2 1.4"/></symbol>
+  <symbol id="i-tasks" viewBox="0 0 16 16"><rect x="2.5" y="2.5" width="11" height="11" rx="2"/><path d="M5.5 6h5M5.5 8.5h5M5.5 11h3"/></symbol>
+  <symbol id="i-coin" viewBox="0 0 16 16"><circle cx="8" cy="8" r="5.5"/><path d="M9.8 6.2c-.3-.6-1-1-1.8-1-1 0-1.8.6-1.8 1.4 0 1.9 3.6 1 3.6 2.9 0 .8-.8 1.4-1.8 1.4-.9 0-1.6-.4-1.9-1.1M8 4v1.2M8 10.9V12"/></symbol>
+  <symbol id="i-act" viewBox="0 0 16 16"><path d="M2.5 4.5h11M2.5 8h11M2.5 11.5h7"/></symbol>
+  <symbol id="i-gear" viewBox="0 0 16 16"><circle cx="8" cy="8" r="2"/><path d="M8 2.2v1.6M8 12.2v1.6M2.2 8h1.6M12.2 8h1.6M3.9 3.9l1.1 1.1M11 11l1.1 1.1M3.9 12.1 5 11M11 5l1.1-1.1"/></symbol>
+  <symbol id="i-back" viewBox="0 0 16 16"><path d="M6.5 4 2.5 8l4 4M2.8 8h10.7"/></symbol>
+  <symbol id="i-pause" viewBox="0 0 16 16"><circle cx="8" cy="8" r="5.5"/><path d="M6.6 6v4M9.4 6v4"/></symbol>
+</svg>
+
+<div class="app">
+  <aside class="side">
+    <div class="logo"><svg viewBox="0 0 22 22" aria-hidden="true"><circle cx="11" cy="11" r="9" fill="none" stroke="currentColor" stroke-width="1.6"/><path d="M5.5 13.5c2-3.4 4-5 5.5-5s3.5 1.6 5.5 5" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"/></svg>ProcessLens <small>Admin</small></div>
+    <nav class="nav">
+      <a class="on" href="#"><svg class="i"><use href="#i-over"/></svg>Overview</a>
+      <a href="#"><svg class="i"><use href="#i-people"/></svg>People</a>
+      <a href="#"><svg class="i"><use href="#i-hist"/></svg>Runs</a>
+      <a href="#"><svg class="i"><use href="#i-tasks"/></svg>Tasks</a>
+      <a href="#"><svg class="i"><use href="#i-coin"/></svg>AI spend</a>
+      <a href="#"><svg class="i"><use href="#i-act"/></svg>Activity</a>
+    </nav>
+    <div class="side-foot">
+      <nav class="nav">
+        <a href="#"><svg class="i"><use href="#i-gear"/></svg>Settings</a>
+        <a href="#"><svg class="i"><use href="#i-back"/></svg>Back to ProcessLens</a>
+      </nav>
+    </div>
+  </aside>
+
+  <main>
+    <div class="head in" style="--i:0">
+      <h2>Overview</h2>
+      <span class="org">Northwind Supply</span>
+      <span class="avatar">JV</span>
+    </div>
+
+    <div class="frozen" id="frozen" hidden>
+      <b>All runs are paused.</b><span>Paused by Jay at <span id="frozen-at">14:02</span>. Nothing new will start.</span>
+      <button class="btn quiet" id="unfreeze" type="button">Let runs start again</button>
+    </div>
+
+    <section class="hero">
+      <div>
+        <h1 class="big in" style="--i:1" id="headline">3 runs going.<br><span>3 things need a look.</span></h1>
+        <p class="lede in" style="--i:2">Example data for the mock. Nothing was entered twice this week.</p>
+      </div>
+      <button class="btn stop in" style="--i:2" id="pause-all" type="button"><svg class="i"><use href="#i-pause"/></svg>Pause everything</button>
+    </section>
+
+    <div class="confirm" id="confirm" hidden>
+      <p>Every run stops at its next safe point. Nothing half-saved is left behind. People can resume their own runs after you let runs start again.</p>
+      <div class="acts">
+        <button class="btn stop solid" id="confirm-yes" type="button">Pause everything</button>
+        <button class="btn quiet" id="confirm-no" type="button">Keep running</button>
+      </div>
+    </div>
+
+    <section class="panel figs in" style="--i:3" aria-label="This week">
+      <div class="fig"><b>1,284</b><span>Rows done this week</span><small>Across 9 people and 6 tasks</small></div>
+      <div class="fig gold"><b>58 h 40 m</b><span>Time saved this week</span><small>vs. about 3 minutes a row by hand</small></div>
+      <div class="fig"><b>$41.20</b><span>AI spend this month</span><small>About 3 cents a row</small></div>
+    </section>
+
+    <section class="two">
+      <div class="panel in" style="--i:4">
+        <div class="panel-h"><h3>Needs a look</h3><a href="#">Activity</a></div>
+        <ul class="rows">
+          <li><div><b>Add vendor bills to Odoo</b><p>Stopped responding 6 minutes ago. Ravi's Chrome may be closed.</p></div><button class="btn quiet" type="button">Open run</button></li>
+          <li><div><b>Update deal stages in Twenty</b><p>Keeps failing. The last 3 runs had more rows not working than done.</p></div><button class="btn quiet" type="button">Open task</button></li>
+          <li><div><b>3 people need to update the Chrome extension</b><p>They're on 1.4.2. New runs need 1.5.0 or newer.</p></div><button class="btn quiet" type="button">See people</button></li>
+        </ul>
+      </div>
+
+      <div class="panel in" style="--i:5">
+        <div class="panel-h"><h3>Running now</h3><a href="#">All runs</a></div>
+        <ul class="rows" id="running">
+          <li><div><b>Add customer inquiries to Odoo CRM</b><p>Priya Nair · started 10:42</p>
+            <div class="track"><i style="width:26%" data-total="500" data-done="128"></i></div>
+            <div class="meta"><span class="res live">Running</span><span class="count">128 of 500 done</span></div></div>
+            <button class="btn quiet" type="button">Pause</button></li>
+          <li><div><b>Import contacts into Twenty</b><p>Jay Vee · started 13:20</p>
+            <div class="track"><i style="width:68%" data-total="60" data-done="41"></i></div>
+            <div class="meta"><span class="res live">Running</span><span class="count">41 of 60 done</span></div></div>
+            <button class="btn quiet" type="button">Pause</button></li>
+          <li><div><b>Add vendor bills to Odoo</b><p>Ravi Iyer · started 09:15</p>
+            <div class="track stalled"><i style="width:44%"></i></div>
+            <div class="meta"><span class="res help">Not responding</span><span>88 of 200 done</span></div></div>
+            <button class="btn quiet" type="button">Pause</button></li>
+        </ul>
+      </div>
+    </section>
+  </main>
+</div>
+
+<script>
+(function () {
+  var $ = function (id) { return document.getElementById(id); };
+  var pauseAll = $("pause-all"), confirmBox = $("confirm"), frozen = $("frozen"), headline = $("headline");
+  pauseAll.addEventListener("click", function () { confirmBox.hidden = false; $("confirm-no").focus(); });
+  $("confirm-no").addEventListener("click", function () { confirmBox.hidden = true; pauseAll.focus(); });
+  $("confirm-yes").addEventListener("click", function () {
+    var now = new Date();
+    $("frozen-at").textContent = String(now.getHours()).padStart(2, "0") + ":" + String(now.getMinutes()).padStart(2, "0");
+    confirmBox.hidden = true; frozen.hidden = false; pauseAll.hidden = true;
+    headline.innerHTML = "Runs are paused.<br><span>3 will stop at their next safe point.</span>";
+    document.querySelectorAll("#running .res.live").forEach(function (el) { el.className = "res idle"; el.textContent = "Pausing"; });
+    $("unfreeze").focus();
+  });
+  $("unfreeze").addEventListener("click", function () {
+    frozen.hidden = true; pauseAll.hidden = false;
+    headline.innerHTML = "Runs can start again.<br><span>People resume their own runs.</span>";
+    pauseAll.focus();
+  });
+  // live progress on the two healthy runs
+  setInterval(function () {
+    if (!frozen.hidden) return;
+    document.querySelectorAll("#running .track:not(.stalled) i").forEach(function (bar) {
+      var total = +bar.dataset.total, done = Math.min(total, +bar.dataset.done + 1);
+      bar.dataset.done = done; bar.style.width = (done / total * 100).toFixed(1) + "%";
+      bar.parentNode.parentNode.querySelector(".count").textContent = done + " of " + total + " done";
+    });
+  }, 2500);
+})();
+</script>