Dispatch board, request idempotency, and the batch 2-5 programme

CLAUDE.md

@@ -165,7 +165,9 @@ OpenInspection runs as ONE Cloudflare Worker (cloudflare/react-router-hono-fulls
 | `APP_BASE_URL` | No | Public URL for OAuth and link generation |
 | `APP_BASE_URL` | No | Public origin used when building absolute links (reports, hosted `/legal/:tenant/…` Privacy & Terms). |
 | `RESEND_API_KEY`| No | Platform-default email delivery (Resend). Tenants may switch to their OWN Resend key + verified sender via Settings → Communication (per-tenant override; the email pipeline resolves own-vs-platform explicitly). |
-| `GEMINI_API_KEY`| No | DEPRECATED as a platform key — AI assistance is strictly bring-your-own-key: `AIService` reads the tenant's own stored key (Settings → Advanced) and ignores this env. AI features stay off until a tenant configures a key. |
+| `GEMINI_API_KEY`| No | Not the credential AI features run on. `AIService` resolves credentials per call (`server/lib/ai/resolve-provider.ts`): a tenant's own stored key (Settings → Advanced → AI) always wins, and in `saas` mode a deployment-provided key may be used instead for tenants the deployment grants managed access to. In `standalone` there is no managed path at all — the tenant's key or nothing. This env is still read by the Advanced-settings "Test connection" diagnostic. |
+| `AI_MODEL` | No | Model id every AI call uses (e.g. a Gemini model name). **No default is compiled in**: when unset, AI features fail closed with a 503 rather than silently pinning whichever model was current when the code was written. Required for any AI feature to work, in every mode. |
+| `AI_MANAGED_API_KEY` | No | Deployment-provided AI key. Used only where `profile.hasManagedAi` is true (`saas`), and only for tenants the deployment grants managed access to; an entitled tenant on a deployment that never provisioned this key gets the feature OFF, not a runtime credential error. Absent in `standalone` by construction rather than disabled by a flag. Usage on this key meters under `ai_translate`/`ai_assist`; usage on a tenant's own key meters under `ai_translate_byo`/`ai_assist_byo` and never counts against a deployment allowance. |
 | `APP_MODE` | No | `standalone` (default) or `saas` — controls tenant resolution |
 | `APP_NAME` | No | Custom branding name |
 | `PRIMARY_COLOR` | No | Custom branding color |

app/components/ConfirmDialog.tsx

@@ -1,7 +1,16 @@
 import { Modal } from "@core/shared-ui";
+import { m } from "~/paraglide/messages";
 
+/**
+ * Both button labels are TRANSLATED, and the confirm label defaults rather than
+ * being hardcoded. They used to be the bare strings "Cancel" and "Delete" —
+ * which meant this one component silently shipped untranslated chrome to every
+ * one of its call sites, in the middle of dialogs whose title and message were
+ * translated. A shared component is the worst place to leave a literal: it does
+ * not look like ten omissions, it looks like one.
+ */
 export function ConfirmDialog({
-  open, title, message, confirmLabel = "Delete", tone = "danger", busy = false, onConfirm, onCancel,
+  open, title, message, confirmLabel, tone = "danger", busy = false, onConfirm, onCancel,
 }: {
   open: boolean;
   title: string;
@@ -29,15 +38,15 @@ export function ConfirmDialog({
             onClick={onCancel}
             className="px-4 py-2 rounded-md border border-ih-border text-[13px] font-bold text-ih-fg-2 hover:bg-ih-bg-muted transition-colors"
           >
-            Cancel
+            {m.common_cancel()}
           </button>
           <button
             type="button"
             onClick={onConfirm}
             disabled={busy}
             className={`px-4 py-2 rounded-md text-[13px] font-bold transition-opacity disabled:opacity-50 ${confirmClass}`}
           >
-            {confirmLabel}
+            {confirmLabel ?? m.common_delete()}
           </button>
         </>
       }

app/components/LocaleSwitcher.test.tsx

@@ -0,0 +1,100 @@
+// @vitest-environment happy-dom
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { beforeEach, describe, expect, it } from "vitest";
+import { createRoutesStub } from "react-router";
+import { LocaleSwitcher } from "./LocaleSwitcher";
+
+/**
+ * The switcher has to do BOTH writes or it is broken in a way that looks like
+ * it works. Cookie only: the choice is lost on the next device, and — worse —
+ * `auth-layout`'s stamp ranks the stored preference above the cookie and
+ * corrects it straight back on the following navigation. Database only: nothing
+ * changes until a round trip completes, so the control appears dead.
+ *
+ * Rendered through a real router stub rather than bare, so the assertion is on
+ * what the PROFILE ACTION actually receives — a spy would pass against a
+ * component that submits to nowhere.
+ */
+function renderSwitcher(serverLocale: string) {
+  const submitted: { intent?: string; locale?: string } = {};
+  const Stub = createRoutesStub([
+    {
+      id: "root",
+      path: "/",
+      loader: () => ({ locale: serverLocale }),
+      Component: () => <LocaleSwitcher />,
+    },
+    {
+      path: "/settings/profile",
+      action: async ({ request }: { request: Request }) => {
+        const fd = await request.formData();
+        submitted.intent = String(fd.get("intent"));
+        submitted.locale = String(fd.get("locale"));
+        return { success: true };
+      },
+    },
+  ]);
+  render(<Stub initialEntries={["/"]} />);
+  return submitted;
+}
+
+describe("LocaleSwitcher", () => {
+  beforeEach(() => {
+    // A cookie surviving between cases would let a test pass on the previous
+    // test's write.
+    document.cookie = "PARAGLIDE_LOCALE=; path=/; max-age=0";
+  });
+
+  it("writes the cookie and persists the choice", async () => {
+    const submitted = renderSwitcher("en");
+    fireEvent.click(await screen.findByRole("radio", { name: /español/i }));
+
+    expect(document.cookie).toContain("PARAGLIDE_LOCALE=es-419");
+    // Persisted as the tag the settings <select> stores, not the Paraglide tag:
+    // saving 'es-419' here and 'en' in the other direction would make Profile
+    // show "Use workspace default" for a preference just set.
+    await waitFor(() => expect(submitted.intent).toBe("set-locale"));
+    expect(submitted.locale).toBe("es-419");
+  });
+
+  it("switches back to English, storing the region-qualified tag", async () => {
+    // The reverse direction, because a switcher that only ever answers Spanish
+    // passes the test above.
+    const submitted = renderSwitcher("es-419");
+    fireEvent.click(await screen.findByRole("radio", { name: /english/i }));
+
+    expect(document.cookie).toContain("PARAGLIDE_LOCALE=en");
+    await waitFor(() => expect(submitted.locale).toBe("en-US"));
+  });
+
+  it("reflects the locale the SERVER rendered, not a local default", async () => {
+    renderSwitcher("es-419");
+    expect(await screen.findByRole("radio", { name: /español/i })).toHaveAttribute(
+      "aria-checked",
+      "true",
+    );
+    expect(screen.getByRole("radio", { name: /english/i })).toHaveAttribute(
+      "aria-checked",
+      "false",
+    );
+  });
+
+  it("does nothing when the current language is re-selected", async () => {
+    const submitted = renderSwitcher("en");
+    fireEvent.click(await screen.findByRole("radio", { name: /english/i }));
+
+    expect(document.cookie).not.toContain("PARAGLIDE_LOCALE=");
+    expect(submitted.intent).toBeUndefined();
+  });
+
+  it("understands a stored tag the cookie contract cannot serve", async () => {
+    // The root loader reports whatever the paraglide scope resolved, but a
+    // regional tag reaching this control must still select a real segment
+    // rather than leaving every one of them unchecked.
+    renderSwitcher("es-MX");
+    expect(await screen.findByRole("radio", { name: /español/i })).toHaveAttribute(
+      "aria-checked",
+      "true",
+    );
+  });
+});

app/components/LocaleSwitcher.tsx

@@ -0,0 +1,76 @@
+import { useFetcher, useRouteLoaderData } from "react-router";
+import { SegmentedControl, type SegmentedControlOption } from "@core/shared-ui";
+import { SUPPORTED_CONTACT_LOCALES, normalizeLocale } from "../../server/lib/i18n/contact-locale";
+import { localeShortLabel, storedLocaleTag } from "~/lib/locales";
+import { writeUiLocaleCookie } from "~/lib/ui-prefs";
+import { m } from "~/paraglide/messages";
+
+/**
+ * The always-reachable language control (#269).
+ *
+ * Two pickers already persist a language — Settings → Profile writes
+ * `users.locale`, Settings → Workspace writes `tenant_configs.default_locale`.
+ * Neither is reachable from the page you are on, and, more to the point,
+ * neither is reachable by someone who cannot read the English word "Settings".
+ * This is the one control a person can find when the interface is in a language
+ * they do not speak, which is why it sits beside the theme control in the user
+ * menu rather than on a settings page.
+ *
+ * Deliberately built on the same `SegmentedControl` as `ThemeSegmentControl`,
+ * next to which it renders: a bespoke dropdown here would be the third language
+ * control in the app and the only one shaped unlike its own neighbour.
+ *
+ * TWO WRITES, and both are needed:
+ *
+ *  1. The COOKIE, written first and synchronously. The worker resolves the
+ *     render locale from it before the router runs (`withResolvedUiLocale`), so
+ *     this is what makes the change take effect on the very next request rather
+ *     than after a database round trip.
+ *  2. `users.locale`, through the existing profile action, so the choice
+ *     survives a new device — and so `auth-layout`'s stamp, which ranks the
+ *     stored preference ABOVE the cookie, agrees with it instead of correcting
+ *     it back on the next navigation.
+ *
+ * The re-render is a consequence of (2), not a separate mechanism: React Router
+ * revalidates every loader after a fetcher submission, so the root loader re-runs
+ * server-side inside the new request's paraglide scope and the whole tree — plus
+ * `<html lang>` — comes back in the new language. No reload, no flash.
+ */
+export function LocaleSwitcher({ className }: { className?: string }) {
+  // Root loader data, exactly as ThemeSegmentControl reads the color scheme:
+  // it is the locale the SERVER rendered this page in, so the control always
+  // shows what the reader is actually looking at rather than what was last
+  // clicked. Absent while the error boundary renders — fall back to English.
+  const rootData = useRouteLoaderData("root") as { locale?: string } | undefined;
+  const current = normalizeLocale(rootData?.locale) ?? "en";
+  const fetcher = useFetcher();
+
+  // Built at render time (not a module const) so `m.*()` resolves inside the
+  // paraglide request scope — same reason ThemeSegmentControl builds its own.
+  //
+  // The option LABELS come from the locale table, not from message keys: a
+  // language name is not translated ("Español" is Español in every language),
+  // and a per-locale key would let the two catalogues disagree about what a
+  // language is called.
+  const options: SegmentedControlOption[] = SUPPORTED_CONTACT_LOCALES.map((value) => ({
+    value,
+    label: localeShortLabel(value),
+  }));
+
+  return (
+    <SegmentedControl
+      options={options}
+      value={current}
+      ariaLabel={m.nav_language_aria()}
+      className={className}
+      onChange={(next) => {
+        if (next === current) return;
+        writeUiLocaleCookie(next);
+        fetcher.submit(
+          { intent: "set-locale", locale: storedLocaleTag(next) },
+          { method: "post", action: "/settings/profile" },
+        );
+      }}
+    />
+  );
+}

app/components/NewInspectionWizard.test.tsx

@@ -14,7 +14,7 @@
  *   - string    → at cap, billingPortalUrl for the "Subscribe" CTA.
  */
 import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { render, fireEvent } from '@testing-library/react';
+import { render, fireEvent, act } from '@testing-library/react';
 import { createElement } from 'react';
 
 const fetcherMocks = {
@@ -208,5 +208,35 @@ describe('NewInspectionWizard — client + buyer-agent payload', () => {
         expect(payload).toHaveProperty('templateId', 'tpl-1');
         // Batch C — the wizard sends the zone it displayed, not a bare local time.
         expect(payload).toHaveProperty('timeZone', 'UTC');
+        // Idempotency (portal #105): the create carries a key the server can
+        // dedupe on. Without it, the guard below only narrows the window.
+        expect(typeof payload.idempotencyKey).toBe('string');
+        expect(payload.idempotencyKey.length).toBeGreaterThan(0);
+    });
+
+    /**
+     * Portal #105, seen in production on 2026-08-05: one tenant created three
+     * byte-identical inspections seconds apart. Create called `fetcher.submit`
+     * with nothing guarding it and the button stayed live, so every impatient
+     * click was another inspection.
+     *
+     * Both clicks go inside ONE act(): React batches the handlers and renders
+     * nothing between them, which is what a real double click looks like and
+     * why a `fetcher.state` check cannot see the second one.
+     */
+    it('creates one inspection when Create is clicked twice in the same tick (portal #105)', () => {
+        const { getAllByRole } = walkToConfirm();
+        const createBtn = (getAllByRole('button') as HTMLButtonElement[])
+            .find((b) => b.textContent?.includes('Create Inspection'));
+        expect(createBtn).toBeTruthy();
+
+        act(() => {
+            createBtn!.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+            createBtn!.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+        });
+
+        const createCalls = fetcherMocks.submit.mock.calls
+            .filter((c) => (c[0] as { intent?: string })?.intent === 'create');
+        expect(createCalls.length).toBe(1);
     });
 });

app/components/NewInspectionWizard.tsx

@@ -1,6 +1,7 @@
 import { useEffect, useMemo, useState } from "react";
 import { useFetcher } from "react-router";
 import { useContactSearch } from "~/hooks/useContactSearch";
+import { useGuardedSubmit } from "~/hooks/useGuardedSubmit";
 import { buildWizardSteps, stepBlockedReason, todayLocalISO, type WizardStepId } from "~/lib/wizard-steps";
 import { summariseNewInspection } from "~/lib/wizard-review";
 import { buildWizardCreatePayload } from "~/lib/wizard-submit";
@@ -92,7 +93,11 @@ export function NewInspectionWizard({
    */
   quotaExceededAtOpen?: string | null;
 }) {
-  const fetcher = useFetcher();
+  // portal #105 — the create submit is guarded, not bare: one in-flight submit
+  // at a time, carrying an idempotency key the server dedupes on. A tenant
+  // created three byte-identical inspections seconds apart because Create was a
+  // plain `fetcher.submit` behind a button that stayed live.
+  const { fetcher, submit: submitCreate, busy: creating } = useGuardedSubmit();
   // The zone the Schedule step names, and the zone the typed time is read in.
   // Both must be the same value or the inspector is told one thing and the
   // booking stores another.
@@ -390,7 +395,10 @@ export function NewInspectionWizard({
   });
 
   function handleSubmit() {
-    fetcher.submit(
+    // Returns false and does nothing if a create is already in flight — the
+    // button below is disabled too, but that only takes effect on the NEXT
+    // render, which a double click beats.
+    submitCreate(
       buildWizardCreatePayload({
         propertyType,
         address,
@@ -435,6 +443,7 @@ export function NewInspectionWizard({
       stepIdx={stepIdx}
       stepLabel={stepLabel}
       blockedReason={blockedReason}
+      busy={creating}
       isLastStep={stepIdx === steps.length - 1}
       onBack={() => (stepIdx > 0 ? setStepIdx(stepIdx - 1) : onClose())}
       onNext={() => (stepIdx < steps.length - 1 ? setStepIdx(stepIdx + 1) : handleSubmit())}

app/components/Sidebar.tsx

@@ -1,8 +1,8 @@
 import { useState, useRef } from "react";
 import { NavLink, useRouteLoaderData } from "react-router";
-import { useSessionContext, useUnreadMessages } from "~/hooks/useSessionContext";
+import { useCapabilities, useSessionContext, useUnreadMessages } from "~/hooks/useSessionContext";
 import { writeSidebarCookie, type UiPrefs } from "~/lib/ui-prefs";
-import { IC, WORKSPACE_ITEMS } from "~/components/sidebar/nav-items";
+import { IC, WORKSPACE_ITEMS, visibleNavItems } from "~/components/sidebar/nav-items";
 import { SidebarGroup } from "~/components/sidebar/SidebarGroup";
 import { UserMenuPopover } from "~/components/sidebar/UserMenuPopover";
 import { MobileHeader } from "~/components/sidebar/MobileHeader";
@@ -21,6 +21,7 @@ export function Sidebar() {
   // flash from the old two-pass localStorage read).
   const rootPrefs = useRouteLoaderData("root") as UiPrefs | undefined;
   const [collapsed, setCollapsed] = useState(rootPrefs?.sidebarCollapsed ?? false);
+  const capabilities = useCapabilities();
   const [userMenuOpen, setUserMenuOpen] = useState(false);
   const userMenuRef = useRef<HTMLDivElement>(null);
   const ctx = useSessionContext();
@@ -98,7 +99,7 @@ export function Sidebar() {
 
       {/* Nav */}
       <nav className="flex-1 px-2 py-1 overflow-y-auto">
-        <SidebarGroup label={m.nav_section_workspace()} items={WORKSPACE_ITEMS.map((i) => (i.to === "/messages" ? { ...i, badge: unreadMessages } : i))} collapsed={collapsed} />
+        <SidebarGroup label={m.nav_section_workspace()} items={visibleNavItems(WORKSPACE_ITEMS, capabilities).map((i) => (i.to === "/messages" ? { ...i, badge: unreadMessages } : i))} collapsed={collapsed} />
         {/* ds-allow: compact sidebar nav rhythm (10/7/14px), no semantic spacing token */}
         <div className="mb-[14px]">
           <NavLink

app/components/agreements/AgreementLanguageDisclosure.test.tsx

@@ -0,0 +1,39 @@
+// @vitest-environment happy-dom
+import { describe, it, expect } from 'vitest';
+import { render } from '@testing-library/react';
+import { AgreementLanguageDisclosure } from './AgreementLanguageDisclosure';
+import { AGREEMENT_LANGUAGE_DISCLOSURE } from '../../../server/lib/legal/agreement-language-disclosure';
+
+// What this file can and cannot settle:
+//
+// It can check what a reader sees. It CANNOT check which allow-list the mount
+// pass uses — DOMPurify under happy-dom drops the outermost element and applies
+// no allow-list at all, so a round trip through it proves nothing about a
+// browser (measured; see tests/unit/agreements/language-disclosure.spec.ts).
+// Worse, the server-sanitized-then-re-sanitized pattern means the wrong
+// component would render identical markup on this first pass, so no synchronous
+// DOM assertion here can tell the two apart. The sanitizer choice is asserted
+// against source in that spec, and confirmed in a real browser.
+
+describe('AgreementLanguageDisclosure', () => {
+  it('states the fact, under a heading that says it is not a term', () => {
+    const { container } = render(<AgreementLanguageDisclosure />);
+    expect(container.textContent).toContain(AGREEMENT_LANGUAGE_DISCLOSURE.label);
+    expect(container.textContent).toMatch(/provided in English/i);
+    expect(container.textContent).toMatch(/translated before signing/i);
+  });
+
+  it('keeps the wrapper that marks it as a note rather than prose', () => {
+    const { container } = render(<AgreementLanguageDisclosure />);
+    const note = container.querySelector('section[role="note"]');
+    expect(note, 'the wrapper is what stops this reading as a loose paragraph').not.toBeNull();
+    expect(note!.textContent).toMatch(/provided in English/i);
+  });
+
+  it('offers nothing to click and nothing to load', () => {
+    // A platform note inside a signing flow is the last place to introduce an
+    // outbound link or a remote asset.
+    const { container } = render(<AgreementLanguageDisclosure />);
+    expect(container.querySelector('a, img, iframe, svg, form')).toBeNull();
+  });
+});