From c62427217cc5905eeccec66bf39ad6fd37cd6d4b Mon Sep 17 00:00:00 2001
From: akxue <18199652+akxue@users.noreply.github.com>
Date: Fri, 23 Oct 2026 02:47:57 +0000
Subject: [PATCH 01/10] Embed the live view for the human intervention step

---
 .changeset/human-intervention-step.md         |   5 +
 packages/demo/src/States.tsx                  |  12 ++
 .../src/KernelManagedAuth.tsx                 |  14 ++
 .../src/appearance/types.ts                   |   3 +
 .../src/components/HumanInterventionStep.tsx  | 111 ++++++++++++++++
 packages/managed-auth-react/src/index.ts      |   1 +
 packages/managed-auth-react/src/lib/types.ts  |   3 +
 .../src/localization/defaults.ts              |   9 ++
 .../src/localization/types.ts                 |   8 ++
 .../managed-auth-react/src/session/state.ts   |   4 +-
 .../src/session/submission.ts                 |  12 ++
 ...nagedAuthSession.humanIntervention.test.ts | 124 ++++++++++++++++++
 .../src/session/useManagedAuthSession.ts      |  28 +++-
 .../managed-auth-react/src/styles/styles.css  |  73 +++++++++++
 14 files changed, 403 insertions(+), 4 deletions(-)
 create mode 100644 .changeset/human-intervention-step.md
 create mode 100644 packages/managed-auth-react/src/components/HumanInterventionStep.tsx
 create mode 100644 packages/managed-auth-react/src/session/useManagedAuthSession.humanIntervention.test.ts

diff --git a/.changeset/human-intervention-step.md b/.changeset/human-intervention-step.md
new file mode 100644
index 0000000..c184b0c
--- /dev/null
+++ b/.changeset/human-intervention-step.md
@@ -0,0 +1,5 @@
+---
+"@onkernel/managed-auth-react": minor
+---
+
+Add the `AWAITING_HUMAN_INTERVENTION` step. When a connection has `hitl` enabled and the login hits a CAPTCHA the browser cannot solve, the component embeds the login browser's live view so the person can complete it, then resumes the login when they confirm. Sites that restrict embedded content with a Content-Security-Policy need to allow the live view origin in `frame-src`.
diff --git a/packages/demo/src/States.tsx b/packages/demo/src/States.tsx
index 39fc0d1..8ba3f14 100644
--- a/packages/demo/src/States.tsx
+++ b/packages/demo/src/States.tsx
@@ -2,6 +2,7 @@ import { useState } from "react";
 import {
   AppearanceProvider,
   ExternalActionWaiting,
+  HumanInterventionStep,
   LoadingState,
   LocalizationProvider,
   Shell,
@@ -79,6 +80,7 @@ type StateName =
   | "awaiting_input_mfa"
   | "awaiting_external_action"
   | "awaiting_external_action_multi"
+  | "awaiting_human_intervention"
   | "submitting"
   | "success"
   | "expired"
@@ -93,6 +95,7 @@ const allStates: StateName[] = [
   "awaiting_input_mfa",
   "awaiting_external_action",
   "awaiting_external_action_multi",
+  "awaiting_human_intervention",
   "submitting",
   "success",
   "expired",
@@ -197,6 +200,15 @@ export function States() {
             onMFASelect={() => {}}
           />
         );
+      case "awaiting_human_intervention":
+        return (
+          <HumanInterventionStep
+            targetDomain={TARGET_DOMAIN}
+            liveViewUrl={null}
+            onDone={handleSubmit}
+            isLoading={isLoading}
+          />
+        );
       case "submitting":
         return (
           <LoadingState message="Logging you in..." variant="authenticating" />
diff --git a/packages/managed-auth-react/src/KernelManagedAuth.tsx b/packages/managed-auth-react/src/KernelManagedAuth.tsx
index 7ba9df4..6a6744a 100644
--- a/packages/managed-auth-react/src/KernelManagedAuth.tsx
+++ b/packages/managed-auth-react/src/KernelManagedAuth.tsx
@@ -10,6 +10,7 @@ import { StepError } from "./components/StepError";
 import { StepExpired } from "./components/StepExpired";
 import { LoadingState } from "./components/LoadingState";
 import { ExternalActionWaiting } from "./components/ExternalActionWaiting";
+import { HumanInterventionStep } from "./components/HumanInterventionStep";
 import { useLocalization } from "./localization/context";
 import type { Appearance } from "./appearance/types";
 import type { Localization } from "./localization/types";
@@ -83,6 +84,7 @@ function KernelManagedAuthInner({
     submitSSO,
     submitMFA,
     submitSignIn,
+    completeHumanIntervention,
   } = session;
 
   const targetDomain = useMemo(() => state?.domain ?? "", [state?.domain]);
@@ -121,6 +123,18 @@ function KernelManagedAuthInner({
     );
   }
 
+  if (uiState === "awaiting_human_intervention") {
+    return (
+      <HumanInterventionStep
+        targetDomain={targetDomain}
+        liveViewUrl={state?.live_view_url}
+        onDone={completeHumanIntervention}
+        isLoading={isSubmitting}
+        errorMessage={submitError ?? undefined}
+      />
+    );
+  }
+
   if (uiState === "success") {
     return <StepSuccess targetDomain={targetDomain} />;
   }
diff --git a/packages/managed-auth-react/src/appearance/types.ts b/packages/managed-auth-react/src/appearance/types.ts
index 4db0796..9993605 100644
--- a/packages/managed-auth-react/src/appearance/types.ts
+++ b/packages/managed-auth-react/src/appearance/types.ts
@@ -123,6 +123,9 @@ export interface AppearanceElements {
   /** External action waiting screen. */
   externalActionIcon?: ElementValue;
   externalActionMessage?: ElementValue;
+  /** Human intervention screen. */
+  humanInterventionMessage?: ElementValue;
+  humanInterventionLiveView?: ElementValue;
   /** Form wrapper. */
   form?: ElementValue;
   formField?: ElementValue;
diff --git a/packages/managed-auth-react/src/components/HumanInterventionStep.tsx b/packages/managed-auth-react/src/components/HumanInterventionStep.tsx
new file mode 100644
index 0000000..536651a
--- /dev/null
+++ b/packages/managed-auth-react/src/components/HumanInterventionStep.tsx
@@ -0,0 +1,111 @@
+import { useEffect, useMemo, useState } from "react";
+import { useSlot } from "../appearance/context";
+import { useLocalization } from "../localization/context";
+import { Button } from "./primitives/Button";
+import { ErrorBanner } from "./ErrorBanner";
+import { ShieldCheckIcon } from "./icons";
+
+// The live view posts one of these when its connection never succeeds.
+const LIVE_VIEW_CONNECT_FAILURES = new Set([
+  "KERNEL_CONNECTION_TIMEOUT",
+  "KERNEL_CONNECTION_FAILED",
+]);
+
+function liveViewOrigin(url: string | null | undefined): string | null {
+  if (!url) return null;
+  try {
+    return new URL(url).origin;
+  } catch {
+    return null;
+  }
+}
+
+interface HumanInterventionStepProps {
+  targetDomain: string;
+  liveViewUrl?: string | null;
+  onDone: () => void;
+  isLoading?: boolean;
+  errorMessage?: string;
+}
+
+export function HumanInterventionStep({
+  targetDomain,
+  liveViewUrl,
+  onDone,
+  isLoading,
+  errorMessage,
+}: HumanInterventionStepProps) {
+  const slot = useSlot();
+  const l = useLocalization();
+  const origin = useMemo(() => liveViewOrigin(liveViewUrl), [liveViewUrl]);
+  const [attempt, setAttempt] = useState(0);
+  const [connectFailed, setConnectFailed] = useState(false);
+
+  useEffect(() => {
+    if (!origin) return;
+    const onMessage = (event: MessageEvent) => {
+      if (event.origin !== origin) return;
+      const type = (event.data as { type?: unknown } | null)?.type;
+      if (typeof type === "string" && LIVE_VIEW_CONNECT_FAILURES.has(type)) {
+        setConnectFailed(true);
+      }
+    };
+    window.addEventListener("message", onMessage);
+    return () => window.removeEventListener("message", onMessage);
+  }, [origin]);
+
+  const retry = () => {
+    setConnectFailed(false);
+    setAttempt((n) => n + 1);
+  };
+
+  return (
+    <div className="kma-step kma-human-intervention">
+      <div className="kma-human-intervention__header">
+        <span className="kma-human-intervention__icon" aria-hidden="true">
+          <ShieldCheckIcon />
+        </span>
+        <div>
+          <h2 className="kma-title">{l.humanInterventionTitle}</h2>
+          <p {...slot("humanInterventionMessage", "kma-subtitle")}>
+            {l.humanInterventionMessage(targetDomain)}
+          </p>
+        </div>
+      </div>
+
+      {errorMessage && <ErrorBanner message={errorMessage} />}
+
+      <div
+        {...slot("humanInterventionLiveView", "kma-human-intervention__frame")}
+      >
+        {origin ? (
+          <iframe
+            key={`${liveViewUrl}-${attempt}`}
+            src={liveViewUrl ?? undefined}
+            title={l.humanInterventionLiveViewTitle}
+            className="kma-human-intervention__iframe"
+            allow="clipboard-read; clipboard-write"
+          />
+        ) : (
+          <p className="kma-human-intervention__notice">
+            {l.humanInterventionLiveViewUnavailable}
+          </p>
+        )}
+        {connectFailed && (
+          <div className="kma-human-intervention__overlay" role="alert">
+            <p className="kma-human-intervention__notice">
+              {l.humanInterventionLiveViewFailed}
+            </p>
+            <Button variant="secondary" onClick={retry}>
+              {l.humanInterventionRetry}
+            </Button>
+          </div>
+        )}
+      </div>
+
+      <Button onClick={onDone} disabled={isLoading}>
+        {l.humanInterventionDone}
+      </Button>
+    </div>
+  );
+}
diff --git a/packages/managed-auth-react/src/index.ts b/packages/managed-auth-react/src/index.ts
index a18e9a8..4154619 100644
--- a/packages/managed-auth-react/src/index.ts
+++ b/packages/managed-auth-react/src/index.ts
@@ -31,6 +31,7 @@ export { StepError } from "./components/StepError";
 export { StepExpired } from "./components/StepExpired";
 export { LoadingState } from "./components/LoadingState";
 export { ExternalActionWaiting } from "./components/ExternalActionWaiting";
+export { HumanInterventionStep } from "./components/HumanInterventionStep";
 export { UnifiedAuthForm } from "./components/UnifiedAuthForm";
 
 export type {
diff --git a/packages/managed-auth-react/src/lib/types.ts b/packages/managed-auth-react/src/lib/types.ts
index 99e0af5..b5ba6a4 100644
--- a/packages/managed-auth-react/src/lib/types.ts
+++ b/packages/managed-auth-react/src/lib/types.ts
@@ -13,6 +13,7 @@ export type FlowStep =
   | "DISCOVERING"
   | "AWAITING_INPUT"
   | "AWAITING_EXTERNAL_ACTION"
+  | "AWAITING_HUMAN_INTERVENTION"
   | "SUBMITTING"
   | "COMPLETED";
 
@@ -90,6 +91,7 @@ export type ManagedAuthChoiceType =
   | "auth_method"
   | "identifier_method"
   | "account"
+  | "human_intervention"
   | "other";
 
 export interface ManagedAuthChoice {
@@ -155,6 +157,7 @@ export type UIState =
   | "discovering"
   | "awaiting_input"
   | "awaiting_external_action"
+  | "awaiting_human_intervention"
   | "submitting"
   | "success"
   | "expired"
diff --git a/packages/managed-auth-react/src/localization/defaults.ts b/packages/managed-auth-react/src/localization/defaults.ts
index 96d759f..242af3e 100644
--- a/packages/managed-auth-react/src/localization/defaults.ts
+++ b/packages/managed-auth-react/src/localization/defaults.ts
@@ -75,4 +75,13 @@ export const DEFAULT_LOCALIZATION: Localizer = {
   externalActionTitle: "Action Required",
   externalActionFallbackMessage: "Complete the verification on your device",
   externalActionWaiting: "Waiting for your confirmation...",
+  humanInterventionTitle: "Complete the security check",
+  humanInterventionMessage: (site) =>
+    `${site} is asking to confirm you're human. Complete the check in the browser below, then continue.`,
+  humanInterventionDone: "I've completed the check",
+  humanInterventionLiveViewTitle: "Login browser",
+  humanInterventionLiveViewUnavailable:
+    "The login browser isn't available right now.",
+  humanInterventionLiveViewFailed: "Couldn't connect to the login browser.",
+  humanInterventionRetry: "Try again",
 };
diff --git a/packages/managed-auth-react/src/localization/types.ts b/packages/managed-auth-react/src/localization/types.ts
index a7a6007..96957db 100644
--- a/packages/managed-auth-react/src/localization/types.ts
+++ b/packages/managed-auth-react/src/localization/types.ts
@@ -63,6 +63,14 @@ export interface Localization {
   externalActionTitle?: string;
   externalActionFallbackMessage?: string;
   externalActionWaiting?: string;
+  /** Human intervention (CAPTCHA the browser could not solve). */
+  humanInterventionTitle?: string;
+  humanInterventionMessage?: (site: string) => string;
+  humanInterventionDone?: string;
+  humanInterventionLiveViewTitle?: string;
+  humanInterventionLiveViewUnavailable?: string;
+  humanInterventionLiveViewFailed?: string;
+  humanInterventionRetry?: string;
 }
 
 export type Localizer = Required<Localization>;
diff --git a/packages/managed-auth-react/src/session/state.ts b/packages/managed-auth-react/src/session/state.ts
index 07840af..2476b93 100644
--- a/packages/managed-auth-react/src/session/state.ts
+++ b/packages/managed-auth-react/src/session/state.ts
@@ -162,7 +162,9 @@ function signInOptionsFromCanonical(
   const options = choices
     .filter(
       (choice) =>
-        choice.type !== "sso_provider" && choice.type !== "mfa_method",
+        choice.type !== "sso_provider" &&
+        choice.type !== "mfa_method" &&
+        choice.type !== "human_intervention",
     )
     .map((choice) => ({
       id: choice.id,
diff --git a/packages/managed-auth-react/src/session/submission.ts b/packages/managed-auth-react/src/session/submission.ts
index 4ed48d7..1bdb423 100644
--- a/packages/managed-auth-react/src/session/submission.ts
+++ b/packages/managed-auth-react/src/session/submission.ts
@@ -49,6 +49,18 @@ export function buildMFASubmission(
     : { fields: {}, mfa_option_id: type };
 }
 
+export function buildHumanInterventionSubmission(
+  state: ManagedAuthResponse | null,
+): ManagedAuthSubmitBody {
+  const choice = state?.choices?.find(
+    (candidate) => candidate.type === "human_intervention",
+  );
+  return {
+    interaction_id: interactionId(state),
+    selected_choice_id: canonicalChoiceId(choice?.id),
+  };
+}
+
 export function buildSignInSubmission(
   state: ManagedAuthResponse | null,
   optionId: string,
diff --git a/packages/managed-auth-react/src/session/useManagedAuthSession.humanIntervention.test.ts b/packages/managed-auth-react/src/session/useManagedAuthSession.humanIntervention.test.ts
new file mode 100644
index 0000000..05fd134
--- /dev/null
+++ b/packages/managed-auth-react/src/session/useManagedAuthSession.humanIntervention.test.ts
@@ -0,0 +1,124 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { createElement } from "react";
+import { act, create, type ReactTestRenderer } from "react-test-renderer";
+import type { ManagedAuthResponse } from "../lib/types";
+import {
+  useManagedAuthSession,
+  type ManagedAuthSessionValue,
+} from "./useManagedAuthSession";
+
+function response(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+const humanInterventionState: ManagedAuthResponse = {
+  id: "session-id",
+  domain: "example.com",
+  profile_name: "profile",
+  flow_status: "IN_PROGRESS",
+  flow_step: "AWAITING_HUMAN_INTERVENTION",
+  interaction_id: "mai_captcha",
+  live_view_url: "https://live.example.com/browser/live/abc",
+  fields: [],
+  choices: [
+    {
+      id: "human_intervention_done",
+      type: "human_intervention",
+      label: "I've completed the security check",
+    },
+  ],
+};
+
+let renderer: ReactTestRenderer | null = null;
+
+afterEach(() => {
+  if (renderer) {
+    act(() => renderer?.unmount());
+    renderer = null;
+  }
+});
+
+async function renderSession(submitResponse: Response) {
+  const submissions: unknown[] = [];
+  let value: ManagedAuthSessionValue | null = null;
+
+  const fetchImpl = (async (
+    input: RequestInfo | URL,
+    init?: RequestInit,
+  ): Promise<Response> => {
+    const url = String(input);
+    if (url.endsWith("/exchange")) return response({ jwt: "jwt" });
+    if (url.endsWith("/events")) return new Promise<Response>(() => {});
+    if (url.endsWith("/submit")) {
+      submissions.push(JSON.parse(String(init?.body)));
+      return submitResponse;
+    }
+    if (init?.method === "GET") return response(humanInterventionState);
+    throw new Error(`Unexpected request: ${init?.method} ${url}`);
+  }) as typeof fetch;
+
+  function Harness() {
+    value = useManagedAuthSession({
+      sessionId: "session-id",
+      handoffCode: "handoff-code",
+      autoStart: true,
+      fetch: fetchImpl,
+    });
+    return null;
+  }
+
+  await act(async () => {
+    renderer = create(createElement(Harness));
+    await Promise.resolve();
+    await Promise.resolve();
+    await Promise.resolve();
+  });
+
+  return {
+    submissions,
+    get value() {
+      if (!value) throw new Error("Session hook did not render");
+      return value;
+    },
+  };
+}
+
+describe("useManagedAuthSession human intervention", () => {
+  test("pauses on the human intervention step and keeps it out of sign-in options", async () => {
+    const session = await renderSession(response({}));
+
+    expect(session.value.uiState).toBe("awaiting_human_intervention");
+    expect(session.value.state?.sign_in_options).toBeNull();
+  });
+
+  test("submits the done choice for the current interaction", async () => {
+    const session = await renderSession(response({}));
+
+    await act(async () => {
+      await session.value.completeHumanIntervention();
+    });
+
+    expect(session.submissions).toEqual([
+      {
+        interaction_id: "mai_captcha",
+        selected_choice_id: "human_intervention_done",
+      },
+    ]);
+  });
+
+  test("returns to the live view when the submit fails", async () => {
+    const session = await renderSession(
+      response({ code: "internal_error", message: "try again" }, 500),
+    );
+
+    await act(async () => {
+      await session.value.completeHumanIntervention();
+    });
+
+    expect(session.value.uiState).toBe("awaiting_human_intervention");
+    expect(session.value.submitError).toBeTruthy();
+  });
+});
diff --git a/packages/managed-auth-react/src/session/useManagedAuthSession.ts b/packages/managed-auth-react/src/session/useManagedAuthSession.ts
index ce7e56b..0ead002 100644
--- a/packages/managed-auth-react/src/session/useManagedAuthSession.ts
+++ b/packages/managed-auth-react/src/session/useManagedAuthSession.ts
@@ -18,6 +18,7 @@ import { normalizeManagedAuthState } from "./state";
 import { createSessionTransport } from "./transport";
 import {
   buildFieldSubmission,
+  buildHumanInterventionSubmission,
   buildMFASubmission,
   buildSignInSubmission,
   buildSSOSubmission,
@@ -37,6 +38,8 @@ function deriveUIState(state: ManagedAuthResponse): UIState {
       return "awaiting_input";
     case "AWAITING_EXTERNAL_ACTION":
       return "awaiting_external_action";
+    case "AWAITING_HUMAN_INTERVENTION":
+      return "awaiting_human_intervention";
     case "SUBMITTING":
       return "submitting";
     default:
@@ -70,6 +73,7 @@ export interface ManagedAuthSessionValue {
   submitSSO: (button: SSOButton) => Promise<void>;
   submitMFA: (mfaType: MFAType, choiceId?: string) => Promise<void>;
   submitSignIn: (optionId: string) => Promise<void>;
+  completeHumanIntervention: () => Promise<void>;
 }
 
 /**
@@ -300,9 +304,12 @@ export function useManagedAuthSession(
           return;
         }
         setSubmitError(msg);
-        setUIState((current) =>
-          isTerminal(current) ? current : "awaiting_input",
-        );
+        setUIState((current) => {
+          if (isTerminal(current)) return current;
+          return stateRef.current?.flow_step === "AWAITING_HUMAN_INTERVENTION"
+            ? "awaiting_human_intervention"
+            : "awaiting_input";
+        });
       } finally {
         if (isActive()) {
           transport?.endSubmission();
@@ -381,6 +388,20 @@ export function useManagedAuthSession(
     [jwt, sessionId, submit, options],
   );
 
+  const completeHumanIntervention = useCallback(async () => {
+    if (!jwt) return;
+    return submit(
+      () =>
+        submitManagedAuth(
+          sessionId,
+          jwt,
+          buildHumanInterventionSubmission(stateRef.current),
+          options,
+        ),
+      "Failed to continue the login",
+    );
+  }, [jwt, sessionId, submit, options]);
+
   return {
     state,
     uiState,
@@ -394,5 +415,6 @@ export function useManagedAuthSession(
     submitSSO,
     submitMFA,
     submitSignIn,
+    completeHumanIntervention,
   };
 }
diff --git a/packages/managed-auth-react/src/styles/styles.css b/packages/managed-auth-react/src/styles/styles.css
index 38203cf..abe514e 100644
--- a/packages/managed-auth-react/src/styles/styles.css
+++ b/packages/managed-auth-react/src/styles/styles.css
@@ -863,6 +863,79 @@
   text-align: center;
 }
 
+/* ---------- Human intervention ---------- */
+
+/* The login browser renders at 1280x800, so the card widens to keep it legible. */
+.kma-shell:has(.kma-human-intervention) {
+  max-width: 64rem;
+}
+
+.kma-human-intervention {
+  gap: 1rem;
+}
+
+.kma-human-intervention__header {
+  display: flex;
+  align-items: flex-start;
+  gap: 0.75rem;
+}
+
+.kma-human-intervention__icon {
+  flex: none;
+  width: 2.5rem;
+  height: 2.5rem;
+  border-radius: 9999px;
+  background: color-mix(in srgb, var(--kma-color-primary) 15%, transparent);
+  color: var(--kma-color-primary-bright, var(--kma-color-primary));
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.kma-human-intervention__icon svg {
+  width: 1.25rem;
+  height: 1.25rem;
+}
+
+.kma-human-intervention__frame {
+  position: relative;
+  width: 100%;
+  aspect-ratio: 16 / 10;
+  border: 1px solid var(--kma-color-border);
+  border-radius: var(--kma-radius);
+  background: var(--kma-color-muted);
+  overflow: hidden;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.kma-human-intervention__iframe {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  border: 0;
+}
+
+.kma-human-intervention__overlay {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 0.75rem;
+  background: color-mix(in srgb, var(--kma-color-background) 90%, transparent);
+}
+
+.kma-human-intervention__notice {
+  margin: 0;
+  font-size: var(--kma-font-size);
+  color: var(--kma-color-muted-foreground);
+  text-align: center;
+}
+
 /* ---------- External action waiting ---------- */
 
 .kma-external-action {

From aaa46e05a7fe8b5e7740e37526b56cb5787081a3 Mon Sep 17 00:00:00 2001
From: akxue <18199652+akxue@users.noreply.github.com>
Date: Mon, 26 Oct 2026 18:46:55 +0000
Subject: [PATCH 02/10] Show a note when the site asks for a security check
 again

---
 .changeset/human-intervention-step.md         |  2 +-
 packages/demo/src/States.tsx                  | 12 ++++
 .../src/KernelManagedAuth.tsx                 |  4 ++
 .../src/appearance/types.ts                   |  1 +
 .../components/HumanInterventionStep.test.tsx | 58 +++++++++++++++++++
 .../src/components/HumanInterventionStep.tsx  | 11 ++++
 .../managed-auth-react/src/styles/styles.css  |  9 +++
 7 files changed, 96 insertions(+), 1 deletion(-)
 create mode 100644 packages/managed-auth-react/src/components/HumanInterventionStep.test.tsx

diff --git a/.changeset/human-intervention-step.md b/.changeset/human-intervention-step.md
index c184b0c..cca68bf 100644
--- a/.changeset/human-intervention-step.md
+++ b/.changeset/human-intervention-step.md
@@ -2,4 +2,4 @@
 "@onkernel/managed-auth-react": minor
 ---
 
-Add the `AWAITING_HUMAN_INTERVENTION` step. When a connection has `hitl` enabled and the login hits a CAPTCHA the browser cannot solve, the component embeds the login browser's live view so the person can complete it, then resumes the login when they confirm. Sites that restrict embedded content with a Content-Security-Policy need to allow the live view origin in `frame-src`.
+Add the `AWAITING_HUMAN_INTERVENTION` step. When a connection has `hitl` enabled and the login hits a CAPTCHA the browser cannot solve, the component embeds the login browser's live view so the person can complete it, then resumes the login when they confirm. If the site asks for another check after the person continues, the screen shows a short note. Sites that restrict embedded content with a Content-Security-Policy need to allow the live view origin in `frame-src`.
diff --git a/packages/demo/src/States.tsx b/packages/demo/src/States.tsx
index 8ba3f14..a689258 100644
--- a/packages/demo/src/States.tsx
+++ b/packages/demo/src/States.tsx
@@ -81,6 +81,7 @@ type StateName =
   | "awaiting_external_action"
   | "awaiting_external_action_multi"
   | "awaiting_human_intervention"
+  | "awaiting_human_intervention_again"
   | "submitting"
   | "success"
   | "expired"
@@ -96,6 +97,7 @@ const allStates: StateName[] = [
   "awaiting_external_action",
   "awaiting_external_action_multi",
   "awaiting_human_intervention",
+  "awaiting_human_intervention_again",
   "submitting",
   "success",
   "expired",
@@ -209,6 +211,16 @@ export function States() {
             isLoading={isLoading}
           />
         );
+      case "awaiting_human_intervention_again":
+        return (
+          <HumanInterventionStep
+            targetDomain={TARGET_DOMAIN}
+            liveViewUrl={null}
+            onDone={handleSubmit}
+            isLoading={isLoading}
+            note="The site is asking for a security check again. Complete it in the browser below, then continue."
+          />
+        );
       case "submitting":
         return (
           <LoadingState message="Logging you in..." variant="authenticating" />
diff --git a/packages/managed-auth-react/src/KernelManagedAuth.tsx b/packages/managed-auth-react/src/KernelManagedAuth.tsx
index 6a6744a..2d3a94e 100644
--- a/packages/managed-auth-react/src/KernelManagedAuth.tsx
+++ b/packages/managed-auth-react/src/KernelManagedAuth.tsx
@@ -131,6 +131,10 @@ function KernelManagedAuthInner({
         onDone={completeHumanIntervention}
         isLoading={isSubmitting}
         errorMessage={submitError ?? undefined}
+        note={
+          state?.choices?.find((choice) => choice.type === "human_intervention")
+            ?.description
+        }
       />
     );
   }
diff --git a/packages/managed-auth-react/src/appearance/types.ts b/packages/managed-auth-react/src/appearance/types.ts
index 9993605..b02072f 100644
--- a/packages/managed-auth-react/src/appearance/types.ts
+++ b/packages/managed-auth-react/src/appearance/types.ts
@@ -126,6 +126,7 @@ export interface AppearanceElements {
   /** Human intervention screen. */
   humanInterventionMessage?: ElementValue;
   humanInterventionLiveView?: ElementValue;
+  humanInterventionNote?: ElementValue;
   /** Form wrapper. */
   form?: ElementValue;
   formField?: ElementValue;
diff --git a/packages/managed-auth-react/src/components/HumanInterventionStep.test.tsx b/packages/managed-auth-react/src/components/HumanInterventionStep.test.tsx
new file mode 100644
index 0000000..87080d0
--- /dev/null
+++ b/packages/managed-auth-react/src/components/HumanInterventionStep.test.tsx
@@ -0,0 +1,58 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { createElement } from "react";
+import { act, create } from "react-test-renderer";
+import { AppearanceProvider } from "../appearance/context";
+import { LocalizationProvider } from "../localization/context";
+import { HumanInterventionStep } from "./HumanInterventionStep";
+
+function render(note?: string) {
+  let renderer!: ReturnType<typeof create>;
+  act(() => {
+    renderer = create(
+      createElement(
+        AppearanceProvider,
+        null,
+        createElement(
+          LocalizationProvider,
+          null,
+          createElement(HumanInterventionStep, {
+            targetDomain: "example.com",
+            liveViewUrl: "https://live.example.com/browser/live/abc",
+            onDone: () => {},
+            note,
+          }),
+        ),
+      ),
+    );
+  });
+  return renderer;
+}
+
+const statusText = (renderer: ReturnType<typeof create>) =>
+  renderer.root
+    .findAll((node) => node.props.role === "status" && node.type === "p")
+    .map((node) => node.children.join(""));
+
+describe("HumanInterventionStep", () => {
+  // The step listens for live view connection failures on window.
+  const hadWindow = "window" in globalThis;
+  beforeAll(() => {
+    if (!hadWindow) {
+      Object.assign(globalThis, {
+        window: { addEventListener() {}, removeEventListener() {} },
+      });
+    }
+  });
+  afterAll(() => {
+    if (!hadWindow) delete (globalThis as { window?: unknown }).window;
+  });
+
+  test("shows the note when the site asks again", () => {
+    const note = "The site is asking for a security check again.";
+    expect(statusText(render(note))).toEqual([note]);
+  });
+
+  test("shows no note on the first pause", () => {
+    expect(statusText(render())).toEqual([]);
+  });
+});
diff --git a/packages/managed-auth-react/src/components/HumanInterventionStep.tsx b/packages/managed-auth-react/src/components/HumanInterventionStep.tsx
index 536651a..92898d6 100644
--- a/packages/managed-auth-react/src/components/HumanInterventionStep.tsx
+++ b/packages/managed-auth-react/src/components/HumanInterventionStep.tsx
@@ -26,6 +26,8 @@ interface HumanInterventionStepProps {
   onDone: () => void;
   isLoading?: boolean;
   errorMessage?: string;
+  /** Shown when the site asks for a check again after the person continued. */
+  note?: string | null;
 }
 
 export function HumanInterventionStep({
@@ -34,6 +36,7 @@ export function HumanInterventionStep({
   onDone,
   isLoading,
   errorMessage,
+  note,
 }: HumanInterventionStepProps) {
   const slot = useSlot();
   const l = useLocalization();
@@ -73,6 +76,14 @@ export function HumanInterventionStep({
         </div>
       </div>
 
+      {note && (
+        <p
+          {...slot("humanInterventionNote", "kma-human-intervention__note")}
+          role="status"
+        >
+          {note}
+        </p>
+      )}
       {errorMessage && <ErrorBanner message={errorMessage} />}
 
       <div
diff --git a/packages/managed-auth-react/src/styles/styles.css b/packages/managed-auth-react/src/styles/styles.css
index abe514e..d90e596 100644
--- a/packages/managed-auth-react/src/styles/styles.css
+++ b/packages/managed-auth-react/src/styles/styles.css
@@ -897,6 +897,15 @@
   height: 1.25rem;
 }
 
+.kma-human-intervention__note {
+  margin: 0;
+  padding: 0.625rem 0.75rem;
+  border-radius: var(--kma-radius-sm);
+  background: color-mix(in srgb, var(--kma-color-warning) 18%, transparent);
+  color: var(--kma-color-foreground);
+  font-size: var(--kma-font-size);
+}
+
 .kma-human-intervention__frame {
   position: relative;
   width: 100%;

From eebd23e9879d3017e391bc4a21a8ee67c87f948d Mon Sep 17 00:00:00 2001
From: akxue <18199652+akxue@users.noreply.github.com>
Date: Mon, 26 Oct 2026 20:51:33 +0000
Subject: [PATCH 03/10] Use human verification wording and a 16:9 live view
 frame

---
 packages/demo/src/States.tsx                         |  2 +-
 .../src/components/HumanInterventionStep.test.tsx    |  2 +-
 .../src/components/HumanInterventionStep.tsx         |  4 ++++
 .../managed-auth-react/src/localization/defaults.ts  |  8 +++++---
 .../managed-auth-react/src/localization/types.ts     |  1 +
 .../useManagedAuthSession.humanIntervention.test.ts  |  2 +-
 packages/managed-auth-react/src/styles/styles.css    | 12 ++++++++++--
 7 files changed, 23 insertions(+), 8 deletions(-)

diff --git a/packages/demo/src/States.tsx b/packages/demo/src/States.tsx
index a689258..1fca9c3 100644
--- a/packages/demo/src/States.tsx
+++ b/packages/demo/src/States.tsx
@@ -218,7 +218,7 @@ export function States() {
             liveViewUrl={null}
             onDone={handleSubmit}
             isLoading={isLoading}
-            note="The site is asking for a security check again. Complete it in the browser below, then continue."
+            note="kernel.sh is asking to verify again."
           />
         );
       case "submitting":
diff --git a/packages/managed-auth-react/src/components/HumanInterventionStep.test.tsx b/packages/managed-auth-react/src/components/HumanInterventionStep.test.tsx
index 87080d0..7691dc6 100644
--- a/packages/managed-auth-react/src/components/HumanInterventionStep.test.tsx
+++ b/packages/managed-auth-react/src/components/HumanInterventionStep.test.tsx
@@ -48,7 +48,7 @@ describe("HumanInterventionStep", () => {
   });
 
   test("shows the note when the site asks again", () => {
-    const note = "The site is asking for a security check again.";
+    const note = "example.com is asking to verify again.";
     expect(statusText(render(note))).toEqual([note]);
   });
 
diff --git a/packages/managed-auth-react/src/components/HumanInterventionStep.tsx b/packages/managed-auth-react/src/components/HumanInterventionStep.tsx
index 92898d6..35b6f0b 100644
--- a/packages/managed-auth-react/src/components/HumanInterventionStep.tsx
+++ b/packages/managed-auth-react/src/components/HumanInterventionStep.tsx
@@ -114,6 +114,10 @@ export function HumanInterventionStep({
         )}
       </div>
 
+      <p className="kma-human-intervention__hint">
+        {l.humanInterventionReassurance}
+      </p>
+
       <Button onClick={onDone} disabled={isLoading}>
         {l.humanInterventionDone}
       </Button>
diff --git a/packages/managed-auth-react/src/localization/defaults.ts b/packages/managed-auth-react/src/localization/defaults.ts
index 242af3e..873dfb4 100644
--- a/packages/managed-auth-react/src/localization/defaults.ts
+++ b/packages/managed-auth-react/src/localization/defaults.ts
@@ -75,10 +75,12 @@ export const DEFAULT_LOCALIZATION: Localizer = {
   externalActionTitle: "Action Required",
   externalActionFallbackMessage: "Complete the verification on your device",
   externalActionWaiting: "Waiting for your confirmation...",
-  humanInterventionTitle: "Complete the security check",
+  humanInterventionTitle: "Human verification required",
   humanInterventionMessage: (site) =>
-    `${site} is asking to confirm you're human. Complete the check in the browser below, then continue.`,
-  humanInterventionDone: "I've completed the check",
+    `${site} needs to confirm a person is signing in. Complete the check below, then continue.`,
+  humanInterventionReassurance:
+    "Only complete the check. We'll continue signing you in after.",
+  humanInterventionDone: "Continue",
   humanInterventionLiveViewTitle: "Login browser",
   humanInterventionLiveViewUnavailable:
     "The login browser isn't available right now.",
diff --git a/packages/managed-auth-react/src/localization/types.ts b/packages/managed-auth-react/src/localization/types.ts
index 96957db..58ac2b3 100644
--- a/packages/managed-auth-react/src/localization/types.ts
+++ b/packages/managed-auth-react/src/localization/types.ts
@@ -66,6 +66,7 @@ export interface Localization {
   /** Human intervention (CAPTCHA the browser could not solve). */
   humanInterventionTitle?: string;
   humanInterventionMessage?: (site: string) => string;
+  humanInterventionReassurance?: string;
   humanInterventionDone?: string;
   humanInterventionLiveViewTitle?: string;
   humanInterventionLiveViewUnavailable?: string;
diff --git a/packages/managed-auth-react/src/session/useManagedAuthSession.humanIntervention.test.ts b/packages/managed-auth-react/src/session/useManagedAuthSession.humanIntervention.test.ts
index 05fd134..1b3a493 100644
--- a/packages/managed-auth-react/src/session/useManagedAuthSession.humanIntervention.test.ts
+++ b/packages/managed-auth-react/src/session/useManagedAuthSession.humanIntervention.test.ts
@@ -27,7 +27,7 @@ const humanInterventionState: ManagedAuthResponse = {
     {
       id: "human_intervention_done",
       type: "human_intervention",
-      label: "I've completed the security check",
+      label: "I've completed the verification",
     },
   ],
 };
diff --git a/packages/managed-auth-react/src/styles/styles.css b/packages/managed-auth-react/src/styles/styles.css
index d90e596..47dbb52 100644
--- a/packages/managed-auth-react/src/styles/styles.css
+++ b/packages/managed-auth-react/src/styles/styles.css
@@ -865,7 +865,7 @@
 
 /* ---------- Human intervention ---------- */
 
-/* The login browser renders at 1280x800, so the card widens to keep it legible. */
+/* The live view shows the login browser at 1920x1080, so the card widens to keep it legible. */
 .kma-shell:has(.kma-human-intervention) {
   max-width: 64rem;
 }
@@ -909,7 +909,8 @@
 .kma-human-intervention__frame {
   position: relative;
   width: 100%;
-  aspect-ratio: 16 / 10;
+  /* The live view streams the whole 1920x1080 display. */
+  aspect-ratio: 16 / 9;
   border: 1px solid var(--kma-color-border);
   border-radius: var(--kma-radius);
   background: var(--kma-color-muted);
@@ -938,6 +939,13 @@
   background: color-mix(in srgb, var(--kma-color-background) 90%, transparent);
 }
 
+.kma-human-intervention__hint {
+  margin: 0;
+  font-size: var(--kma-font-size-sm);
+  color: var(--kma-color-muted-foreground);
+  text-align: center;
+}
+
 .kma-human-intervention__notice {
   margin: 0;
   font-size: var(--kma-font-size);

From cc260f92ba0ac63755adfa6c569d0806db0d1444 Mon Sep 17 00:00:00 2001
From: akxue <18199652+akxue@users.noreply.github.com>
Date: Mon, 26 Oct 2026 21:12:23 +0000
Subject: [PATCH 04/10] Draw the live view frame border outside the 16:9 box

---
 packages/managed-auth-react/src/styles/styles.css | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/packages/managed-auth-react/src/styles/styles.css b/packages/managed-auth-react/src/styles/styles.css
index 47dbb52..d9c637b 100644
--- a/packages/managed-auth-react/src/styles/styles.css
+++ b/packages/managed-auth-react/src/styles/styles.css
@@ -911,7 +911,8 @@
   width: 100%;
   /* The live view streams the whole 1920x1080 display. */
   aspect-ratio: 16 / 9;
-  border: 1px solid var(--kma-color-border);
+  /* A border would shrink the 16:9 box and pillarbox the stream. */
+  box-shadow: 0 0 0 1px var(--kma-color-border);
   border-radius: var(--kma-radius);
   background: var(--kma-color-muted);
   overflow: hidden;

From dc3ac9e53f0323c2b6fa036d07170e607e14891a Mon Sep 17 00:00:00 2001
From: akxue <18199652+akxue@users.noreply.github.com>
Date: Mon, 26 Oct 2026 21:21:03 +0000
Subject: [PATCH 05/10] Center the human verification heading and move the
 instructions by the button

---
 .../src/components/HumanInterventionStep.tsx  | 17 ++++----------
 .../src/localization/defaults.ts              |  4 +---
 .../src/localization/types.ts                 |  1 -
 .../managed-auth-react/src/styles/styles.css  | 23 +++----------------
 4 files changed, 8 insertions(+), 37 deletions(-)

diff --git a/packages/managed-auth-react/src/components/HumanInterventionStep.tsx b/packages/managed-auth-react/src/components/HumanInterventionStep.tsx
index 35b6f0b..0abd051 100644
--- a/packages/managed-auth-react/src/components/HumanInterventionStep.tsx
+++ b/packages/managed-auth-react/src/components/HumanInterventionStep.tsx
@@ -3,7 +3,6 @@ import { useSlot } from "../appearance/context";
 import { useLocalization } from "../localization/context";
 import { Button } from "./primitives/Button";
 import { ErrorBanner } from "./ErrorBanner";
-import { ShieldCheckIcon } from "./icons";
 
 // The live view posts one of these when its connection never succeeds.
 const LIVE_VIEW_CONNECT_FAILURES = new Set([
@@ -64,16 +63,8 @@ export function HumanInterventionStep({
 
   return (
     <div className="kma-step kma-human-intervention">
-      <div className="kma-human-intervention__header">
-        <span className="kma-human-intervention__icon" aria-hidden="true">
-          <ShieldCheckIcon />
-        </span>
-        <div>
-          <h2 className="kma-title">{l.humanInterventionTitle}</h2>
-          <p {...slot("humanInterventionMessage", "kma-subtitle")}>
-            {l.humanInterventionMessage(targetDomain)}
-          </p>
-        </div>
+      <div className="kma-step__header kma-human-intervention__header">
+        <h1 {...slot("title", "kma-title")}>{l.humanInterventionTitle}</h1>
       </div>
 
       {note && (
@@ -114,8 +105,8 @@ export function HumanInterventionStep({
         )}
       </div>
 
-      <p className="kma-human-intervention__hint">
-        {l.humanInterventionReassurance}
+      <p {...slot("humanInterventionMessage", "kma-human-intervention__hint")}>
+        {l.humanInterventionMessage(targetDomain)}
       </p>
 
       <Button onClick={onDone} disabled={isLoading}>
diff --git a/packages/managed-auth-react/src/localization/defaults.ts b/packages/managed-auth-react/src/localization/defaults.ts
index 873dfb4..1178d7c 100644
--- a/packages/managed-auth-react/src/localization/defaults.ts
+++ b/packages/managed-auth-react/src/localization/defaults.ts
@@ -77,9 +77,7 @@ export const DEFAULT_LOCALIZATION: Localizer = {
   externalActionWaiting: "Waiting for your confirmation...",
   humanInterventionTitle: "Human verification required",
   humanInterventionMessage: (site) =>
-    `${site} needs to confirm a person is signing in. Complete the check below, then continue.`,
-  humanInterventionReassurance:
-    "Only complete the check. We'll continue signing you in after.",
+    `Complete the check in ${site} above, then continue. We'll continue signing you in after.`,
   humanInterventionDone: "Continue",
   humanInterventionLiveViewTitle: "Login browser",
   humanInterventionLiveViewUnavailable:
diff --git a/packages/managed-auth-react/src/localization/types.ts b/packages/managed-auth-react/src/localization/types.ts
index 58ac2b3..96957db 100644
--- a/packages/managed-auth-react/src/localization/types.ts
+++ b/packages/managed-auth-react/src/localization/types.ts
@@ -66,7 +66,6 @@ export interface Localization {
   /** Human intervention (CAPTCHA the browser could not solve). */
   humanInterventionTitle?: string;
   humanInterventionMessage?: (site: string) => string;
-  humanInterventionReassurance?: string;
   humanInterventionDone?: string;
   humanInterventionLiveViewTitle?: string;
   humanInterventionLiveViewUnavailable?: string;
diff --git a/packages/managed-auth-react/src/styles/styles.css b/packages/managed-auth-react/src/styles/styles.css
index d9c637b..23b081f 100644
--- a/packages/managed-auth-react/src/styles/styles.css
+++ b/packages/managed-auth-react/src/styles/styles.css
@@ -874,27 +874,9 @@
   gap: 1rem;
 }
 
+/* The live view needs clear separation from the heading above it. */
 .kma-human-intervention__header {
-  display: flex;
-  align-items: flex-start;
-  gap: 0.75rem;
-}
-
-.kma-human-intervention__icon {
-  flex: none;
-  width: 2.5rem;
-  height: 2.5rem;
-  border-radius: 9999px;
-  background: color-mix(in srgb, var(--kma-color-primary) 15%, transparent);
-  color: var(--kma-color-primary-bright, var(--kma-color-primary));
-  display: flex;
-  align-items: center;
-  justify-content: center;
-}
-
-.kma-human-intervention__icon svg {
-  width: 1.25rem;
-  height: 1.25rem;
+  margin-bottom: 8px;
 }
 
 .kma-human-intervention__note {
@@ -904,6 +886,7 @@
   background: color-mix(in srgb, var(--kma-color-warning) 18%, transparent);
   color: var(--kma-color-foreground);
   font-size: var(--kma-font-size);
+  text-align: center;
 }
 
 .kma-human-intervention__frame {

From 2422326a2b367cfd75e5ef7b5053e8873e68aa76 Mon Sep 17 00:00:00 2001
From: akxue <18199652+akxue@users.noreply.github.com>
Date: Mon, 26 Oct 2026 21:22:55 +0000
Subject: [PATCH 06/10] Shorten the live view card comment

---
 packages/managed-auth-react/src/styles/styles.css | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/managed-auth-react/src/styles/styles.css b/packages/managed-auth-react/src/styles/styles.css
index 23b081f..5ba1c3a 100644
--- a/packages/managed-auth-react/src/styles/styles.css
+++ b/packages/managed-auth-react/src/styles/styles.css
@@ -865,7 +865,7 @@
 
 /* ---------- Human intervention ---------- */
 
-/* The live view shows the login browser at 1920x1080, so the card widens to keep it legible. */
+/* The card widens so the 1920x1080 live view stays legible. */
 .kma-shell:has(.kma-human-intervention) {
   max-width: 64rem;
 }

From f7fd9330ccc0791634914cfbc54e33917c44dca0 Mon Sep 17 00:00:00 2001
From: akxue <18199652+akxue@users.noreply.github.com>
Date: Mon, 26 Oct 2026 22:22:55 +0000
Subject: [PATCH 07/10] Address review: live view watchdog, keep the step
 mounted, derive the fallback screen

---
 .changeset/human-intervention-step.md         |   2 +-
 packages/managed-auth-react/README.md         |   7 +-
 .../src/KernelManagedAuth.tsx                 |  36 ++---
 .../src/components/HumanInterventionStep.tsx  |  69 +--------
 .../src/components/LiveViewFrame.test.tsx     | 133 +++++++++++++++++
 .../src/components/LiveViewFrame.tsx          | 141 ++++++++++++++++++
 .../src/components/StepError.test.tsx         |  41 ++++-
 .../src/components/StepError.tsx              |  11 +-
 .../src/localization/defaults.ts              |   4 +
 .../src/localization/types.ts                 |   2 +
 .../managed-auth-react/src/session/state.ts   |   7 +
 .../src/session/submission.ts                 |  12 --
 ...nagedAuthSession.humanIntervention.test.ts |   4 +-
 .../src/session/useManagedAuthSession.ts      |  21 +--
 14 files changed, 367 insertions(+), 123 deletions(-)
 create mode 100644 packages/managed-auth-react/src/components/LiveViewFrame.test.tsx
 create mode 100644 packages/managed-auth-react/src/components/LiveViewFrame.tsx

diff --git a/.changeset/human-intervention-step.md b/.changeset/human-intervention-step.md
index cca68bf..eb6d063 100644
--- a/.changeset/human-intervention-step.md
+++ b/.changeset/human-intervention-step.md
@@ -2,4 +2,4 @@
 "@onkernel/managed-auth-react": minor
 ---
 
-Add the `AWAITING_HUMAN_INTERVENTION` step. When a connection has `hitl` enabled and the login hits a CAPTCHA the browser cannot solve, the component embeds the login browser's live view so the person can complete it, then resumes the login when they confirm. If the site asks for another check after the person continues, the screen shows a short note. Sites that restrict embedded content with a Content-Security-Policy need to allow the live view origin in `frame-src`.
+Add the `AWAITING_HUMAN_INTERVENTION` step. When a connection has `hitl` enabled and the login hits a CAPTCHA the browser cannot solve, the component embeds the login browser's live view so the person can complete it, then resumes the login when they confirm. If the site asks for another check after the person continues, the screen shows a short note. Sites that restrict embedded content with a Content-Security-Policy need to allow the live view origin in `frame-src`. The `captcha_blocked` error screen now shows the API's `error_message`, which says whether a person was asked to verify and didn't finish in time.
diff --git a/packages/managed-auth-react/README.md b/packages/managed-auth-react/README.md
index 58dd9ac..a350c25 100644
--- a/packages/managed-auth-react/README.md
+++ b/packages/managed-auth-react/README.md
@@ -260,6 +260,7 @@ import {
   StepExpired,
   LoadingState,
   ExternalActionWaiting,
+  HumanInterventionStep,
   UnifiedAuthForm,
   AppearanceProvider,
   LocalizationProvider,
@@ -270,10 +271,14 @@ Wrap them in `<AppearanceProvider>` and `<LocalizationProvider>` to inherit the
 
 ### Element keys
 
-`root`, `shell`, `card`, `poweredBy`, `poweredByLink`, `poweredByLogo`, `siteIcon`, `title`, `subtitle`, `description`, `securityCard`, `securityRow`, `securityIcon`, `securityText`, `label`, `inputWrapper`, `input`, `inputHint`, `passwordToggle`, `button`, `buttonPrimary`, `buttonSecondary`, `divider`, `dividerLine`, `dividerText`, `ssoButton`, `ssoButtonIcon`, `ssoButtonLabel`, `mfaOption`, `mfaOptionIcon`, `mfaOptionLabel`, `mfaOptionTarget`, `mfaOptionDescription`, `signInOption`, `signInOptionLabel`, `signInOptionDescription`, `signInOptionChevron`, `errorBanner`, `errorBannerText`, `errorIcon`, `errorTitle`, `errorDescription`, `errorCode`, `successIcon`, `successTitle`, `successDescription`, `expiredIcon`, `expiredCard`, `expiredTitle`, `expiredDescription`, `spinner`, `loadingText`, `externalActionIcon`, `externalActionMessage`, `form`, `formField`, `legalText`, `legalLink`.
+`root`, `shell`, `card`, `poweredBy`, `poweredByLink`, `poweredByLogo`, `siteIcon`, `title`, `subtitle`, `description`, `securityCard`, `securityRow`, `securityIcon`, `securityText`, `label`, `inputWrapper`, `input`, `inputHint`, `passwordToggle`, `button`, `buttonPrimary`, `buttonSecondary`, `divider`, `dividerLine`, `dividerText`, `ssoButton`, `ssoButtonIcon`, `ssoButtonLabel`, `mfaOption`, `mfaOptionIcon`, `mfaOptionLabel`, `mfaOptionTarget`, `mfaOptionDescription`, `signInOption`, `signInOptionLabel`, `signInOptionDescription`, `signInOptionChevron`, `errorBanner`, `errorBannerText`, `errorIcon`, `errorTitle`, `errorDescription`, `errorCode`, `successIcon`, `successTitle`, `successDescription`, `expiredIcon`, `expiredCard`, `expiredTitle`, `expiredDescription`, `spinner`, `loadingText`, `externalActionIcon`, `externalActionMessage`, `humanInterventionMessage`, `humanInterventionNote`, `humanInterventionLiveView`, `form`, `formField`, `legalText`, `legalLink`.
 
 `ssoButton`, `mfaOption`, and `signInOption` compose `button` → `buttonSecondary` → the slot-specific key, so any styling applied at `buttonSecondary` (e.g. a shared hover state) flows through to all three.
 
+## Human verification
+
+When a connection has `hitl` enabled and a login hits a CAPTCHA the browser can't solve, the flow pauses at `AWAITING_HUMAN_INTERVENTION` and the component embeds the login browser's live view so the person can complete the check, then continue. If your page sets a Content-Security-Policy, allow the live view's origin (the origin of `live_view_url`) in `frame-src`, or the browser frame is blocked.
+
 ## License
 
 MIT
diff --git a/packages/managed-auth-react/src/KernelManagedAuth.tsx b/packages/managed-auth-react/src/KernelManagedAuth.tsx
index 2d3a94e..9718f52 100644
--- a/packages/managed-auth-react/src/KernelManagedAuth.tsx
+++ b/packages/managed-auth-react/src/KernelManagedAuth.tsx
@@ -11,6 +11,7 @@ import { StepExpired } from "./components/StepExpired";
 import { LoadingState } from "./components/LoadingState";
 import { ExternalActionWaiting } from "./components/ExternalActionWaiting";
 import { HumanInterventionStep } from "./components/HumanInterventionStep";
+import { humanInterventionChoice } from "./session/state";
 import { useLocalization } from "./localization/context";
 import type { Appearance } from "./appearance/types";
 import type { Localization } from "./localization/types";
@@ -84,7 +85,6 @@ function KernelManagedAuthInner({
     submitSSO,
     submitMFA,
     submitSignIn,
-    completeHumanIntervention,
   } = session;
 
   const targetDomain = useMemo(() => state?.domain ?? "", [state?.domain]);
@@ -106,6 +106,24 @@ function KernelManagedAuthInner({
     );
   }
 
+  // Stays mounted while Continue is in flight so the live view isn't torn down.
+  const humanIntervention = humanInterventionChoice(state);
+  if (
+    humanIntervention &&
+    (uiState === "awaiting_human_intervention" || uiState === "submitting")
+  ) {
+    return (
+      <HumanInterventionStep
+        targetDomain={targetDomain}
+        liveViewUrl={state?.live_view_url}
+        onDone={() => submitSignIn(humanIntervention.id)}
+        isLoading={isSubmitting}
+        errorMessage={submitError ?? undefined}
+        note={humanIntervention.description}
+      />
+    );
+  }
+
   if (uiState === "submitting") {
     return (
       <LoadingState message={l.submittingMessage} variant="authenticating" />
@@ -123,22 +141,6 @@ function KernelManagedAuthInner({
     );
   }
 
-  if (uiState === "awaiting_human_intervention") {
-    return (
-      <HumanInterventionStep
-        targetDomain={targetDomain}
-        liveViewUrl={state?.live_view_url}
-        onDone={completeHumanIntervention}
-        isLoading={isSubmitting}
-        errorMessage={submitError ?? undefined}
-        note={
-          state?.choices?.find((choice) => choice.type === "human_intervention")
-            ?.description
-        }
-      />
-    );
-  }
-
   if (uiState === "success") {
     return <StepSuccess targetDomain={targetDomain} />;
   }
diff --git a/packages/managed-auth-react/src/components/HumanInterventionStep.tsx b/packages/managed-auth-react/src/components/HumanInterventionStep.tsx
index 0abd051..1cb5c44 100644
--- a/packages/managed-auth-react/src/components/HumanInterventionStep.tsx
+++ b/packages/managed-auth-react/src/components/HumanInterventionStep.tsx
@@ -1,23 +1,9 @@
-import { useEffect, useMemo, useState } from "react";
 import { useSlot } from "../appearance/context";
 import { useLocalization } from "../localization/context";
+import { extractDomainName } from "../lib/profile-name";
 import { Button } from "./primitives/Button";
 import { ErrorBanner } from "./ErrorBanner";
-
-// The live view posts one of these when its connection never succeeds.
-const LIVE_VIEW_CONNECT_FAILURES = new Set([
-  "KERNEL_CONNECTION_TIMEOUT",
-  "KERNEL_CONNECTION_FAILED",
-]);
-
-function liveViewOrigin(url: string | null | undefined): string | null {
-  if (!url) return null;
-  try {
-    return new URL(url).origin;
-  } catch {
-    return null;
-  }
-}
+import { LiveViewFrame } from "./LiveViewFrame";
 
 interface HumanInterventionStepProps {
   targetDomain: string;
@@ -39,27 +25,6 @@ export function HumanInterventionStep({
 }: HumanInterventionStepProps) {
   const slot = useSlot();
   const l = useLocalization();
-  const origin = useMemo(() => liveViewOrigin(liveViewUrl), [liveViewUrl]);
-  const [attempt, setAttempt] = useState(0);
-  const [connectFailed, setConnectFailed] = useState(false);
-
-  useEffect(() => {
-    if (!origin) return;
-    const onMessage = (event: MessageEvent) => {
-      if (event.origin !== origin) return;
-      const type = (event.data as { type?: unknown } | null)?.type;
-      if (typeof type === "string" && LIVE_VIEW_CONNECT_FAILURES.has(type)) {
-        setConnectFailed(true);
-      }
-    };
-    window.addEventListener("message", onMessage);
-    return () => window.removeEventListener("message", onMessage);
-  }, [origin]);
-
-  const retry = () => {
-    setConnectFailed(false);
-    setAttempt((n) => n + 1);
-  };
 
   return (
     <div className="kma-step kma-human-intervention">
@@ -77,36 +42,10 @@ export function HumanInterventionStep({
       )}
       {errorMessage && <ErrorBanner message={errorMessage} />}
 
-      <div
-        {...slot("humanInterventionLiveView", "kma-human-intervention__frame")}
-      >
-        {origin ? (
-          <iframe
-            key={`${liveViewUrl}-${attempt}`}
-            src={liveViewUrl ?? undefined}
-            title={l.humanInterventionLiveViewTitle}
-            className="kma-human-intervention__iframe"
-            allow="clipboard-read; clipboard-write"
-          />
-        ) : (
-          <p className="kma-human-intervention__notice">
-            {l.humanInterventionLiveViewUnavailable}
-          </p>
-        )}
-        {connectFailed && (
-          <div className="kma-human-intervention__overlay" role="alert">
-            <p className="kma-human-intervention__notice">
-              {l.humanInterventionLiveViewFailed}
-            </p>
-            <Button variant="secondary" onClick={retry}>
-              {l.humanInterventionRetry}
-            </Button>
-          </div>
-        )}
-      </div>
+      <LiveViewFrame url={liveViewUrl} />
 
       <p {...slot("humanInterventionMessage", "kma-human-intervention__hint")}>
-        {l.humanInterventionMessage(targetDomain)}
+        {l.humanInterventionMessage(extractDomainName(targetDomain))}
       </p>
 
       <Button onClick={onDone} disabled={isLoading}>
diff --git a/packages/managed-auth-react/src/components/LiveViewFrame.test.tsx b/packages/managed-auth-react/src/components/LiveViewFrame.test.tsx
new file mode 100644
index 0000000..728c9b5
--- /dev/null
+++ b/packages/managed-auth-react/src/components/LiveViewFrame.test.tsx
@@ -0,0 +1,133 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { createElement } from "react";
+import { act, create, type ReactTestRenderer } from "react-test-renderer";
+import { AppearanceProvider } from "../appearance/context";
+import { LocalizationProvider } from "../localization/context";
+import { DEFAULT_LOCALIZATION } from "../localization";
+import { LiveViewFrame } from "./LiveViewFrame";
+
+const URL_ = "https://live.example.com/browser/live/abc";
+const ORIGIN = "https://live.example.com";
+let listener: ((event: MessageEvent) => void) | undefined;
+
+// The frame listens for live view messages on window.
+const hadWindow = "window" in globalThis;
+beforeAll(() => {
+  if (!hadWindow) {
+    Object.assign(globalThis, {
+      window: {
+        addEventListener: (_: string, fn: (event: MessageEvent) => void) => {
+          listener = fn;
+        },
+        removeEventListener: () => {
+          listener = undefined;
+        },
+      },
+    });
+  }
+});
+afterAll(() => {
+  if (!hadWindow) delete (globalThis as { window?: unknown }).window;
+});
+
+function render(startTimeoutMs = 60_000) {
+  let renderer!: ReactTestRenderer;
+  act(() => {
+    renderer = create(
+      createElement(
+        AppearanceProvider,
+        null,
+        createElement(
+          LocalizationProvider,
+          null,
+          createElement(LiveViewFrame, { url: URL_, startTimeoutMs }),
+        ),
+      ),
+    );
+  });
+  return renderer;
+}
+
+function post(data: unknown, origin = ORIGIN) {
+  act(() => listener?.({ origin, data } as MessageEvent));
+}
+
+const alertText = (renderer: ReactTestRenderer) =>
+  renderer.root
+    .findAll((node) => node.props.role === "alert" && node.type === "div")
+    .map((node) =>
+      node
+        .findAll((child) => child.type === "p")
+        .map((p) => p.children.join(""))
+        .join(""),
+    );
+const buttons = (renderer: ReactTestRenderer) =>
+  renderer.root.findAll((node) => node.type === "button");
+
+describe("LiveViewFrame", () => {
+  test("offers one retry for a network failure, then stops offering it", () => {
+    const renderer = render();
+    post({ type: "KERNEL_CONNECTION_FAILED", reason: "transport" });
+    expect(alertText(renderer)).toEqual([
+      DEFAULT_LOCALIZATION.humanInterventionLiveViewFailed!,
+    ]);
+    expect(buttons(renderer)).toHaveLength(1);
+
+    act(() => buttons(renderer)[0]!.props.onClick());
+    expect(alertText(renderer)).toEqual([]);
+
+    post({ type: "KERNEL_CONNECTION_FAILED", reason: "transport" });
+    expect(alertText(renderer)).toEqual([
+      DEFAULT_LOCALIZATION.humanInterventionLiveViewGaveUp!,
+    ]);
+    expect(buttons(renderer)).toHaveLength(0);
+    act(() => renderer.unmount());
+  });
+
+  test("does not offer a retry when the viewer's browser can't play the stream", () => {
+    const renderer = render();
+    post({ type: "KERNEL_CONNECTION_FAILED", reason: "unsupported" });
+    expect(alertText(renderer)).toEqual([
+      DEFAULT_LOCALIZATION.humanInterventionLiveViewUnsupported!,
+    ]);
+    expect(buttons(renderer)).toHaveLength(0);
+    act(() => renderer.unmount());
+  });
+
+  test("ignores messages from other origins", () => {
+    const renderer = render();
+    post(
+      { type: "KERNEL_CONNECTION_FAILED", reason: "transport" },
+      "https://evil.example",
+    );
+    expect(alertText(renderer)).toEqual([]);
+    act(() => renderer.unmount());
+  });
+
+  test("reloads a viewer that never plays, then reports it", async () => {
+    const renderer = render(20);
+    const iframes: unknown[] = [];
+    for (let i = 0; i < 3; i++) {
+      iframes.push(renderer.root.findByType("iframe" as never));
+      await act(async () => {
+        await new Promise((resolve) => setTimeout(resolve, 40));
+      });
+    }
+    expect(new Set(iframes).size).toBe(3);
+    expect(alertText(renderer)).toEqual([
+      DEFAULT_LOCALIZATION.humanInterventionLiveViewGaveUp!,
+    ]);
+    expect(buttons(renderer)).toHaveLength(0);
+    act(() => renderer.unmount());
+  });
+
+  test("a playing viewer is left alone", async () => {
+    const renderer = render(20);
+    post({ type: "KERNEL_PLAYING", playing: true });
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 60));
+    });
+    expect(alertText(renderer)).toEqual([]);
+    act(() => renderer.unmount());
+  });
+});
diff --git a/packages/managed-auth-react/src/components/LiveViewFrame.tsx b/packages/managed-auth-react/src/components/LiveViewFrame.tsx
new file mode 100644
index 0000000..83ae09e
--- /dev/null
+++ b/packages/managed-auth-react/src/components/LiveViewFrame.tsx
@@ -0,0 +1,141 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import { useSlot } from "../appearance/context";
+import { useLocalization } from "../localization/context";
+import { Button } from "./primitives/Button";
+
+// The live view's connect bounds sum to 48s; the watchdog has to outlast them.
+const LIVE_VIEW_START_TIMEOUT_MS = 60_000;
+// Reloads after a silent stall before telling the person.
+const LIVE_VIEW_AUTO_RELOADS = 2;
+
+type Failure = "retryable" | "gave_up" | "unsupported";
+
+interface LiveViewMessage {
+  type?: unknown;
+  reason?: unknown;
+  iceConnectionState?: unknown;
+}
+
+// A network-path failure can clear on a retry; a property of the viewer's
+// browser repeats on every reload.
+function connectFailure(message: LiveViewMessage): Failure {
+  if (message.reason === "transport") return "retryable";
+  if (
+    message.reason === "peer" &&
+    (message.iceConnectionState === "failed" ||
+      message.iceConnectionState === "closed")
+  ) {
+    return "retryable";
+  }
+  return message.reason === "unsupported" ? "unsupported" : "gave_up";
+}
+
+function liveViewOrigin(url: string | null | undefined): string | null {
+  if (!url) return null;
+  try {
+    return new URL(url).origin;
+  } catch {
+    return null;
+  }
+}
+
+interface LiveViewFrameProps {
+  url?: string | null;
+  /** How long to wait for video before reloading; overridable for tests. */
+  startTimeoutMs?: number;
+}
+
+/**
+ * Embeds a browser's live view and recovers from a viewer that never starts,
+ * following the live view's postMessage protocol.
+ */
+export function LiveViewFrame({
+  url,
+  startTimeoutMs = LIVE_VIEW_START_TIMEOUT_MS,
+}: LiveViewFrameProps) {
+  const slot = useSlot();
+  const l = useLocalization();
+  const origin = useMemo(() => liveViewOrigin(url), [url]);
+  const [attempt, setAttempt] = useState(0);
+  const [failure, setFailure] = useState<Failure | null>(null);
+  const autoReloads = useRef(0);
+  const retried = useRef(false);
+
+  useEffect(() => {
+    if (!origin || failure) return;
+    let watchdog: ReturnType<typeof setTimeout> | undefined;
+    const arm = () => {
+      clearTimeout(watchdog);
+      watchdog = setTimeout(() => {
+        if (autoReloads.current < LIVE_VIEW_AUTO_RELOADS) {
+          autoReloads.current++;
+          setAttempt((n) => n + 1);
+        } else {
+          setFailure("gave_up");
+        }
+      }, startTimeoutMs);
+    };
+    const onMessage = (event: MessageEvent) => {
+      if (event.origin !== origin) return;
+      const message = (event.data ?? {}) as LiveViewMessage;
+      if (message.type === "KERNEL_PLAYING") clearTimeout(watchdog);
+      else if (message.type === "KERNEL_PAUSED") arm();
+      else if (
+        message.type === "KERNEL_CONNECTION_FAILED" ||
+        message.type === "KERNEL_CONNECTION_TIMEOUT"
+      ) {
+        clearTimeout(watchdog);
+        const next = connectFailure(message);
+        setFailure(next === "retryable" && retried.current ? "gave_up" : next);
+      }
+    };
+    window.addEventListener("message", onMessage);
+    arm();
+    return () => {
+      clearTimeout(watchdog);
+      window.removeEventListener("message", onMessage);
+    };
+  }, [origin, attempt, failure, startTimeoutMs]);
+
+  const retry = () => {
+    retried.current = true;
+    setFailure(null);
+    setAttempt((n) => n + 1);
+  };
+
+  return (
+    <div
+      {...slot("humanInterventionLiveView", "kma-human-intervention__frame")}
+    >
+      {origin ? (
+        <iframe
+          key={`${url}-${attempt}`}
+          src={url ?? undefined}
+          title={l.humanInterventionLiveViewTitle}
+          className="kma-human-intervention__iframe"
+          allow="autoplay; clipboard-read; clipboard-write"
+        />
+      ) : (
+        <p className="kma-human-intervention__notice">
+          {l.humanInterventionLiveViewUnavailable}
+        </p>
+      )}
+      {failure && (
+        <div className="kma-human-intervention__overlay" role="alert">
+          <p className="kma-human-intervention__notice">
+            {failure === "retryable"
+              ? l.humanInterventionLiveViewFailed
+              : failure === "unsupported"
+                ? l.humanInterventionLiveViewUnsupported
+                : l.humanInterventionLiveViewGaveUp}
+          </p>
+          {failure === "retryable" && (
+            <Button variant="secondary" onClick={retry}>
+              {l.humanInterventionRetry}
+            </Button>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/packages/managed-auth-react/src/components/StepError.test.tsx b/packages/managed-auth-react/src/components/StepError.test.tsx
index fcb2dc4..e4e748e 100644
--- a/packages/managed-auth-react/src/components/StepError.test.tsx
+++ b/packages/managed-auth-react/src/components/StepError.test.tsx
@@ -1,5 +1,7 @@
 import { describe, expect, test } from "bun:test";
-import { errorDisplayForCode } from "./StepError";
+import { createElement } from "react";
+import { act, create } from "react-test-renderer";
+import { errorDisplayForCode, StepError } from "./StepError";
 
 describe("errorDisplayForCode", () => {
   test("renders typed challenge outcomes with context-neutral copy", () => {
@@ -15,7 +17,7 @@ describe("errorDisplayForCode", () => {
     for (const [code, title] of cases) {
       const display = errorDisplayForCode(code);
       expect(display?.title).toBe(title);
-      expect(display?.description.toLowerCase()).not.toContain("reauth");
+      expect(display?.description?.toLowerCase()).not.toContain("reauth");
     }
   });
 
@@ -41,3 +43,38 @@ describe("errorDisplayForCode", () => {
     expect(display).not.toEqual(invalidCredentials);
   });
 });
+
+describe("StepError description", () => {
+  const timeout =
+    "A CAPTCHA blocked the login. A person was asked to complete it but didn't finish in time. Please try again.";
+
+  test("shows how a captcha_blocked flow ended instead of a fixed description", () => {
+    const hadWindow = "window" in globalThis;
+    if (!hadWindow) {
+      Object.assign(globalThis, {
+        window: { addEventListener() {}, removeEventListener() {} },
+        document: { readyState: "loading" },
+      });
+    }
+    let renderer!: ReturnType<typeof create>;
+    act(() => {
+      renderer = create(
+        createElement(StepError, {
+          targetDomain: "example.com",
+          errorCode: "captcha_blocked",
+          errorMessage: timeout,
+        }),
+      );
+    });
+    const texts = renderer.root
+      .findAll((node) => node.type === "p")
+      .map((node) => node.children.join(""));
+    expect(texts).toContain(timeout);
+    expect(renderer.root.findAll((node) => node.type === "button")).toEqual([]);
+    act(() => renderer.unmount());
+    if (!hadWindow) {
+      delete (globalThis as { window?: unknown }).window;
+      delete (globalThis as { document?: unknown }).document;
+    }
+  });
+});
diff --git a/packages/managed-auth-react/src/components/StepError.tsx b/packages/managed-auth-react/src/components/StepError.tsx
index cbf3012..17f5801 100644
--- a/packages/managed-auth-react/src/components/StepError.tsx
+++ b/packages/managed-auth-react/src/components/StepError.tsx
@@ -11,7 +11,9 @@ interface StepErrorProps {
   errorCode?: string;
 }
 
-const ERROR_DISPLAY: Record<string, { title: string; description: string }> = {
+// Without a description, the screen shows the server's error_message, which
+// says how the flow ended (e.g. a person was asked and didn't finish in time).
+const ERROR_DISPLAY: Record<string, { title: string; description?: string }> = {
   domain_not_allowed: {
     title: "Domain not allowed",
     description:
@@ -65,7 +67,6 @@ const ERROR_DISPLAY: Record<string, { title: string; description: string }> = {
   },
   captcha_blocked: {
     title: "Verification required",
-    description: "A CAPTCHA challenge blocked the login.",
   },
   stuck_in_loop: {
     title: "Login couldn't complete",
@@ -130,11 +131,13 @@ export function StepError({
 
   const display = errorDisplayForCode(errorCode);
   const title = display?.title ?? l.errorTitle;
-  const description = display?.description ?? l.errorGenericMessage;
-
   const rawDetails = errorMessage?.trim()
     ? extractErrorText(errorMessage)
     : undefined;
+  const description =
+    display?.description ??
+    (display ? rawDetails : undefined) ??
+    l.errorGenericMessage;
   const hasDetails = rawDetails && rawDetails !== description;
 
   return (
diff --git a/packages/managed-auth-react/src/localization/defaults.ts b/packages/managed-auth-react/src/localization/defaults.ts
index 1178d7c..0ac347c 100644
--- a/packages/managed-auth-react/src/localization/defaults.ts
+++ b/packages/managed-auth-react/src/localization/defaults.ts
@@ -83,5 +83,9 @@ export const DEFAULT_LOCALIZATION: Localizer = {
   humanInterventionLiveViewUnavailable:
     "The login browser isn't available right now.",
   humanInterventionLiveViewFailed: "Couldn't connect to the login browser.",
+  humanInterventionLiveViewGaveUp:
+    "Couldn't connect to the login browser. Reload this page to try again.",
+  humanInterventionLiveViewUnsupported:
+    "Your browser can't show the login browser. Try a different browser.",
   humanInterventionRetry: "Try again",
 };
diff --git a/packages/managed-auth-react/src/localization/types.ts b/packages/managed-auth-react/src/localization/types.ts
index 96957db..49edaa1 100644
--- a/packages/managed-auth-react/src/localization/types.ts
+++ b/packages/managed-auth-react/src/localization/types.ts
@@ -70,6 +70,8 @@ export interface Localization {
   humanInterventionLiveViewTitle?: string;
   humanInterventionLiveViewUnavailable?: string;
   humanInterventionLiveViewFailed?: string;
+  humanInterventionLiveViewGaveUp?: string;
+  humanInterventionLiveViewUnsupported?: string;
   humanInterventionRetry?: string;
 }
 
diff --git a/packages/managed-auth-react/src/session/state.ts b/packages/managed-auth-react/src/session/state.ts
index 2476b93..35698f4 100644
--- a/packages/managed-auth-react/src/session/state.ts
+++ b/packages/managed-auth-react/src/session/state.ts
@@ -156,6 +156,13 @@ function mfaOptionsFromCanonical(
   return options.length ? options : null;
 }
 
+/** The choice that resumes a human-intervention pause, if one is pending. */
+export function humanInterventionChoice(
+  state: ManagedAuthResponse | null,
+): ManagedAuthChoice | undefined {
+  return state?.choices?.find((choice) => choice.type === "human_intervention");
+}
+
 function signInOptionsFromCanonical(
   choices: ManagedAuthChoice[],
 ): SignInOption[] | null {
diff --git a/packages/managed-auth-react/src/session/submission.ts b/packages/managed-auth-react/src/session/submission.ts
index 1bdb423..4ed48d7 100644
--- a/packages/managed-auth-react/src/session/submission.ts
+++ b/packages/managed-auth-react/src/session/submission.ts
@@ -49,18 +49,6 @@ export function buildMFASubmission(
     : { fields: {}, mfa_option_id: type };
 }
 
-export function buildHumanInterventionSubmission(
-  state: ManagedAuthResponse | null,
-): ManagedAuthSubmitBody {
-  const choice = state?.choices?.find(
-    (candidate) => candidate.type === "human_intervention",
-  );
-  return {
-    interaction_id: interactionId(state),
-    selected_choice_id: canonicalChoiceId(choice?.id),
-  };
-}
-
 export function buildSignInSubmission(
   state: ManagedAuthResponse | null,
   optionId: string,
diff --git a/packages/managed-auth-react/src/session/useManagedAuthSession.humanIntervention.test.ts b/packages/managed-auth-react/src/session/useManagedAuthSession.humanIntervention.test.ts
index 1b3a493..ecd2425 100644
--- a/packages/managed-auth-react/src/session/useManagedAuthSession.humanIntervention.test.ts
+++ b/packages/managed-auth-react/src/session/useManagedAuthSession.humanIntervention.test.ts
@@ -98,7 +98,7 @@ describe("useManagedAuthSession human intervention", () => {
     const session = await renderSession(response({}));
 
     await act(async () => {
-      await session.value.completeHumanIntervention();
+      await session.value.submitSignIn("human_intervention_done");
     });
 
     expect(session.submissions).toEqual([
@@ -115,7 +115,7 @@ describe("useManagedAuthSession human intervention", () => {
     );
 
     await act(async () => {
-      await session.value.completeHumanIntervention();
+      await session.value.submitSignIn("human_intervention_done");
     });
 
     expect(session.value.uiState).toBe("awaiting_human_intervention");
diff --git a/packages/managed-auth-react/src/session/useManagedAuthSession.ts b/packages/managed-auth-react/src/session/useManagedAuthSession.ts
index 0ead002..8a636d9 100644
--- a/packages/managed-auth-react/src/session/useManagedAuthSession.ts
+++ b/packages/managed-auth-react/src/session/useManagedAuthSession.ts
@@ -18,7 +18,6 @@ import { normalizeManagedAuthState } from "./state";
 import { createSessionTransport } from "./transport";
 import {
   buildFieldSubmission,
-  buildHumanInterventionSubmission,
   buildMFASubmission,
   buildSignInSubmission,
   buildSSOSubmission,
@@ -73,7 +72,6 @@ export interface ManagedAuthSessionValue {
   submitSSO: (button: SSOButton) => Promise<void>;
   submitMFA: (mfaType: MFAType, choiceId?: string) => Promise<void>;
   submitSignIn: (optionId: string) => Promise<void>;
-  completeHumanIntervention: () => Promise<void>;
 }
 
 /**
@@ -306,8 +304,8 @@ export function useManagedAuthSession(
         setSubmitError(msg);
         setUIState((current) => {
           if (isTerminal(current)) return current;
-          return stateRef.current?.flow_step === "AWAITING_HUMAN_INTERVENTION"
-            ? "awaiting_human_intervention"
+          return stateRef.current
+            ? deriveUIState(stateRef.current)
             : "awaiting_input";
         });
       } finally {
@@ -388,20 +386,6 @@ export function useManagedAuthSession(
     [jwt, sessionId, submit, options],
   );
 
-  const completeHumanIntervention = useCallback(async () => {
-    if (!jwt) return;
-    return submit(
-      () =>
-        submitManagedAuth(
-          sessionId,
-          jwt,
-          buildHumanInterventionSubmission(stateRef.current),
-          options,
-        ),
-      "Failed to continue the login",
-    );
-  }, [jwt, sessionId, submit, options]);
-
   return {
     state,
     uiState,
@@ -415,6 +399,5 @@ export function useManagedAuthSession(
     submitSSO,
     submitMFA,
     submitSignIn,
-    completeHumanIntervention,
   };
 }

From 09a20525315a1085a84401fad20f6b92b1740889 Mon Sep 17 00:00:00 2001
From: akxue <18199652+akxue@users.noreply.github.com>
Date: Wed, 28 Oct 2026 19:09:25 +0000
Subject: [PATCH 08/10] Keep Continue disabled until the flow moves past the
 pause

---
 .../src/KernelManagedAuth.test.tsx            | 69 +++++++++++++++++++
 .../src/KernelManagedAuth.tsx                 |  2 +-
 2 files changed, 70 insertions(+), 1 deletion(-)

diff --git a/packages/managed-auth-react/src/KernelManagedAuth.test.tsx b/packages/managed-auth-react/src/KernelManagedAuth.test.tsx
index 0a92e78..4b9b66a 100644
--- a/packages/managed-auth-react/src/KernelManagedAuth.test.tsx
+++ b/packages/managed-auth-react/src/KernelManagedAuth.test.tsx
@@ -59,3 +59,72 @@ describe("KernelManagedAuth initialization", () => {
     expect(renderer!.root.findAllByType("button")).toHaveLength(0);
   });
 });
+
+describe("KernelManagedAuth human verification", () => {
+  const hadWindow = "window" in globalThis;
+  // Unmount first: the live view removes its window listener on the way out.
+  afterEach(() => {
+    act(() => renderer?.unmount());
+    renderer = null;
+    if (!hadWindow) delete (globalThis as { window?: unknown }).window;
+  });
+
+  test("keeps Continue disabled after the submit is accepted, until the flow moves on", async () => {
+    if (!hadWindow) {
+      Object.assign(globalThis, {
+        window: { addEventListener() {}, removeEventListener() {} },
+      });
+    }
+    const json = (body: unknown) =>
+      new Response(JSON.stringify(body), {
+        headers: { "Content-Type": "application/json" },
+      });
+    const fetchImpl = (async (input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.endsWith("/exchange")) return json({ jwt: "jwt" });
+      if (url.endsWith("/events")) return new Promise<Response>(() => {});
+      if (url.endsWith("/submit")) return json({});
+      return json({
+        id: "session-id",
+        domain: "example.com",
+        profile_name: "profile",
+        flow_status: "IN_PROGRESS",
+        flow_step: "AWAITING_HUMAN_INTERVENTION",
+        interaction_id: "mai_captcha",
+        live_view_url: "https://live.example.com/browser/live/abc",
+        fields: [],
+        choices: [
+          {
+            id: "human_intervention_done",
+            type: "human_intervention",
+            label: "I've completed the verification",
+          },
+        ],
+      });
+    }) as typeof fetch;
+
+    await act(async () => {
+      renderer = create(
+        createElement(KernelManagedAuth, {
+          sessionId: "session-id",
+          handoffCode: "handoff-code",
+          fetch: fetchImpl,
+          appearance: { layout: { skipPrimeStep: true } },
+        }),
+      );
+      for (let i = 0; i < 5; i++) await Promise.resolve();
+    });
+    const continueButton = () =>
+      renderer!.root.findAll(
+        (node) => node.type === "button" && node.children.includes("Continue"),
+      )[0]!;
+    expect(continueButton().props.disabled).toBe(false);
+
+    await act(async () => {
+      continueButton().props.onClick();
+      for (let i = 0; i < 5; i++) await Promise.resolve();
+    });
+
+    expect(continueButton().props.disabled).toBe(true);
+  });
+});
diff --git a/packages/managed-auth-react/src/KernelManagedAuth.tsx b/packages/managed-auth-react/src/KernelManagedAuth.tsx
index 9718f52..c2d8a04 100644
--- a/packages/managed-auth-react/src/KernelManagedAuth.tsx
+++ b/packages/managed-auth-react/src/KernelManagedAuth.tsx
@@ -117,7 +117,7 @@ function KernelManagedAuthInner({
         targetDomain={targetDomain}
         liveViewUrl={state?.live_view_url}
         onDone={() => submitSignIn(humanIntervention.id)}
-        isLoading={isSubmitting}
+        isLoading={isSubmitting || uiState === "submitting"}
         errorMessage={submitError ?? undefined}
         note={humanIntervention.description}
       />

From 87d22b1eb5c66a5e51c1a315867591749bb88069 Mon Sep 17 00:00:00 2001
From: akxue <18199652+akxue@users.noreply.github.com>
Date: Thu, 29 Oct 2026 18:02:29 +0000
Subject: [PATCH 09/10] Share the leave-submitting update, keep a captcha
 fallback description, and reset the live view on a new url

---
 .../components/HumanInterventionStep.test.tsx | 66 ++++++++++++++-----
 .../src/components/HumanInterventionStep.tsx  |  2 +-
 .../src/components/StepError.test.tsx         | 21 ++++--
 .../src/components/StepError.tsx              | 13 ++--
 .../src/session/useManagedAuthSession.ts      | 20 +++---
 5 files changed, 85 insertions(+), 37 deletions(-)

diff --git a/packages/managed-auth-react/src/components/HumanInterventionStep.test.tsx b/packages/managed-auth-react/src/components/HumanInterventionStep.test.tsx
index 7691dc6..f0cd18d 100644
--- a/packages/managed-auth-react/src/components/HumanInterventionStep.test.tsx
+++ b/packages/managed-auth-react/src/components/HumanInterventionStep.test.tsx
@@ -5,25 +5,30 @@ import { AppearanceProvider } from "../appearance/context";
 import { LocalizationProvider } from "../localization/context";
 import { HumanInterventionStep } from "./HumanInterventionStep";
 
+const LIVE_VIEW = "https://live.example.com/browser/live/abc";
+let listener: ((event: MessageEvent) => void) | undefined;
+
+function step(note?: string, liveViewUrl = LIVE_VIEW) {
+  return createElement(
+    AppearanceProvider,
+    null,
+    createElement(
+      LocalizationProvider,
+      null,
+      createElement(HumanInterventionStep, {
+        targetDomain: "example.com",
+        liveViewUrl,
+        onDone: () => {},
+        note,
+      }),
+    ),
+  );
+}
+
 function render(note?: string) {
   let renderer!: ReturnType<typeof create>;
   act(() => {
-    renderer = create(
-      createElement(
-        AppearanceProvider,
-        null,
-        createElement(
-          LocalizationProvider,
-          null,
-          createElement(HumanInterventionStep, {
-            targetDomain: "example.com",
-            liveViewUrl: "https://live.example.com/browser/live/abc",
-            onDone: () => {},
-            note,
-          }),
-        ),
-      ),
-    );
+    renderer = create(step(note));
   });
   return renderer;
 }
@@ -39,7 +44,14 @@ describe("HumanInterventionStep", () => {
   beforeAll(() => {
     if (!hadWindow) {
       Object.assign(globalThis, {
-        window: { addEventListener() {}, removeEventListener() {} },
+        window: {
+          addEventListener: (_: string, fn: (event: MessageEvent) => void) => {
+            listener = fn;
+          },
+          removeEventListener: () => {
+            listener = undefined;
+          },
+        },
       });
     }
   });
@@ -55,4 +67,24 @@ describe("HumanInterventionStep", () => {
   test("shows no note on the first pause", () => {
     expect(statusText(render())).toEqual([]);
   });
+
+  test("starts the live view fresh when its url changes", () => {
+    const renderer = render();
+    act(() =>
+      listener?.({
+        origin: "https://live.example.com",
+        data: { type: "KERNEL_CONNECTION_FAILED", reason: "unsupported" },
+      } as MessageEvent),
+    );
+    const alerts = () =>
+      renderer.root.findAll((node) => node.props.role === "alert");
+    expect(alerts()).toHaveLength(1);
+
+    const next = "https://live.example.com/browser/live/def";
+    act(() => renderer.update(step(undefined, next)));
+
+    expect(alerts()).toHaveLength(0);
+    expect(renderer.root.findByType("iframe" as never).props.src).toBe(next);
+    act(() => renderer.unmount());
+  });
 });
diff --git a/packages/managed-auth-react/src/components/HumanInterventionStep.tsx b/packages/managed-auth-react/src/components/HumanInterventionStep.tsx
index 1cb5c44..70a8aad 100644
--- a/packages/managed-auth-react/src/components/HumanInterventionStep.tsx
+++ b/packages/managed-auth-react/src/components/HumanInterventionStep.tsx
@@ -42,7 +42,7 @@ export function HumanInterventionStep({
       )}
       {errorMessage && <ErrorBanner message={errorMessage} />}
 
-      <LiveViewFrame url={liveViewUrl} />
+      <LiveViewFrame key={liveViewUrl ?? ""} url={liveViewUrl} />
 
       <p {...slot("humanInterventionMessage", "kma-human-intervention__hint")}>
         {l.humanInterventionMessage(extractDomainName(targetDomain))}
diff --git a/packages/managed-auth-react/src/components/StepError.test.tsx b/packages/managed-auth-react/src/components/StepError.test.tsx
index e4e748e..a0877e5 100644
--- a/packages/managed-auth-react/src/components/StepError.test.tsx
+++ b/packages/managed-auth-react/src/components/StepError.test.tsx
@@ -48,7 +48,7 @@ describe("StepError description", () => {
   const timeout =
     "A CAPTCHA blocked the login. A person was asked to complete it but didn't finish in time. Please try again.";
 
-  test("shows how a captcha_blocked flow ended instead of a fixed description", () => {
+  function paragraphs(errorMessage?: string) {
     const hadWindow = "window" in globalThis;
     if (!hadWindow) {
       Object.assign(globalThis, {
@@ -62,19 +62,32 @@ describe("StepError description", () => {
         createElement(StepError, {
           targetDomain: "example.com",
           errorCode: "captcha_blocked",
-          errorMessage: timeout,
+          errorMessage,
         }),
       );
     });
     const texts = renderer.root
       .findAll((node) => node.type === "p")
       .map((node) => node.children.join(""));
-    expect(texts).toContain(timeout);
-    expect(renderer.root.findAll((node) => node.type === "button")).toEqual([]);
+    const buttonCount = renderer.root.findAll(
+      (node) => node.type === "button",
+    ).length;
     act(() => renderer.unmount());
     if (!hadWindow) {
       delete (globalThis as { window?: unknown }).window;
       delete (globalThis as { document?: unknown }).document;
     }
+    return { texts, buttonCount };
+  }
+
+  test("shows how a captcha_blocked flow ended instead of a fixed description", () => {
+    const { texts, buttonCount } = paragraphs(timeout);
+    expect(texts).toContain(timeout);
+    expect(buttonCount).toBe(0);
+  });
+
+  test("falls back to the captcha description when the server sends no message", () => {
+    const { texts } = paragraphs();
+    expect(texts).toContain("A CAPTCHA blocked the login.");
   });
 });
diff --git a/packages/managed-auth-react/src/components/StepError.tsx b/packages/managed-auth-react/src/components/StepError.tsx
index 17f5801..44623a3 100644
--- a/packages/managed-auth-react/src/components/StepError.tsx
+++ b/packages/managed-auth-react/src/components/StepError.tsx
@@ -11,9 +11,12 @@ interface StepErrorProps {
   errorCode?: string;
 }
 
-// Without a description, the screen shows the server's error_message, which
-// says how the flow ended (e.g. a person was asked and didn't finish in time).
-const ERROR_DISPLAY: Record<string, { title: string; description?: string }> = {
+// preferServerMessage shows the server's error_message when there is one, since
+// it says how the flow ended (e.g. a person was asked and didn't finish in time).
+const ERROR_DISPLAY: Record<
+  string,
+  { title: string; description: string; preferServerMessage?: boolean }
+> = {
   domain_not_allowed: {
     title: "Domain not allowed",
     description:
@@ -67,6 +70,8 @@ const ERROR_DISPLAY: Record<string, { title: string; description?: string }> = {
   },
   captcha_blocked: {
     title: "Verification required",
+    description: "A CAPTCHA blocked the login.",
+    preferServerMessage: true,
   },
   stuck_in_loop: {
     title: "Login couldn't complete",
@@ -135,8 +140,8 @@ export function StepError({
     ? extractErrorText(errorMessage)
     : undefined;
   const description =
+    (display?.preferServerMessage ? rawDetails : undefined) ??
     display?.description ??
-    (display ? rawDetails : undefined) ??
     l.errorGenericMessage;
   const hasDetails = rawDetails && rawDetails !== description;
 
diff --git a/packages/managed-auth-react/src/session/useManagedAuthSession.ts b/packages/managed-auth-react/src/session/useManagedAuthSession.ts
index 8a636d9..3af6d09 100644
--- a/packages/managed-auth-react/src/session/useManagedAuthSession.ts
+++ b/packages/managed-auth-react/src/session/useManagedAuthSession.ts
@@ -278,6 +278,13 @@ export function useManagedAuthSession(
         exchangeRef.current?.active === true;
 
       const transport = transportRef.current;
+      // A failed submit returns to whatever screen the session is on.
+      const leaveSubmitting = () =>
+        setUIState((current) =>
+          current === "submitting" && stateRef.current
+            ? deriveUIState(stateRef.current)
+            : current,
+        );
       transport?.beginSubmission();
       setIsSubmitting(true);
       setSubmitError(null);
@@ -294,20 +301,11 @@ export function useManagedAuthSession(
           await transport?.resync();
           if (!isActive()) return;
           setSubmitError(msg);
-          setUIState((current) =>
-            current === "submitting" && stateRef.current
-              ? deriveUIState(stateRef.current)
-              : current,
-          );
+          leaveSubmitting();
           return;
         }
         setSubmitError(msg);
-        setUIState((current) => {
-          if (isTerminal(current)) return current;
-          return stateRef.current
-            ? deriveUIState(stateRef.current)
-            : "awaiting_input";
-        });
+        leaveSubmitting();
       } finally {
         if (isActive()) {
           transport?.endSubmission();

From 221ea9f24ecaf54f7868d6fdbd3af0529582129b Mon Sep 17 00:00:00 2001
From: akxue <18199652+akxue@users.noreply.github.com>
Date: Fri, 30 Oct 2026 01:16:09 +0000
Subject: [PATCH 10/10] Bump @onkernel/sdk to 0.138.0 for the human
 verification step

---
 bun.lock                                     | 6 +++---
 package.json                                 | 2 +-
 packages/managed-auth-react/src/lib/types.ts | 2 +-
 3 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/bun.lock b/bun.lock
index f7813c2..feae260 100644
--- a/bun.lock
+++ b/bun.lock
@@ -7,7 +7,7 @@
       "devDependencies": {
         "@changesets/changelog-github": "0.7.0",
         "@changesets/cli": "^2.27.0",
-        "@onkernel/sdk": "0.93.0",
+        "@onkernel/sdk": "0.138.0",
         "@types/bun": "1.2.21",
         "@types/node": "^20",
         "@types/react-test-renderer": "18.3.1",
@@ -34,7 +34,7 @@
     },
     "packages/managed-auth-react": {
       "name": "@onkernel/managed-auth-react",
-      "version": "0.2.0",
+      "version": "0.5.5",
       "dependencies": {
         "clsx": "^2.1.1",
         "tldts": "7.4.15",
@@ -210,7 +210,7 @@
 
     "@onkernel/managed-auth-react-demo": ["@onkernel/managed-auth-react-demo@workspace:packages/demo"],
 
-    "@onkernel/sdk": ["@onkernel/sdk@0.93.0", "", {}, "sha512-Hb28fq/XGoDbJGOZXHX7MPdFbBs9OtVER44Xo1p6VT4123xpQMVHCGdR4AdW2KuEEwJpXd1yxuTn0GPvUG8dXw=="],
+    "@onkernel/sdk": ["@onkernel/sdk@0.138.0", "", {}, "sha512-K1H89zavs6kj7E8tIsG46UqKKwEeJ1bD0XAj4c/yFl2zMx6MB1k31uy9rhIddwTmV6qe+P0E43am8TpqUsjkDA=="],
 
     "@rolldown/pluginutils": ["@rolldown/pluginutils@1.0.0-beta.27", "", {}, "sha512-+d0F4MKMCbeVUJwG96uQ4SgAznZNSq93I3V+9NHA4OpvqG8mRCpGdKmK8l/dl02h2CCDHwW2FqilnTyDcAnqjA=="],
 
diff --git a/package.json b/package.json
index 405b379..40f92a6 100644
--- a/package.json
+++ b/package.json
@@ -19,7 +19,7 @@
   "devDependencies": {
     "@changesets/changelog-github": "0.7.0",
     "@changesets/cli": "^2.27.0",
-    "@onkernel/sdk": "0.93.0",
+    "@onkernel/sdk": "0.138.0",
     "@types/bun": "1.2.21",
     "@types/node": "^20",
     "@types/react-test-renderer": "18.3.1",
diff --git a/packages/managed-auth-react/src/lib/types.ts b/packages/managed-auth-react/src/lib/types.ts
index b5ba6a4..482ee69 100644
--- a/packages/managed-auth-react/src/lib/types.ts
+++ b/packages/managed-auth-react/src/lib/types.ts
@@ -1,5 +1,5 @@
 // Protocol types for Kernel managed auth.
-// Synchronized with @onkernel/sdk v0.93.0 and vendored to keep this package runtime-free.
+// Synchronized with @onkernel/sdk v0.138.0 and vendored to keep this package runtime-free.
 
 export type FlowStatus =
   | "PENDING"