feat(cli): surface v1.56 verification attempt detail in doctor + agent status

Pairs with gateway v1.56 (parent change: verification-no-silent-fail in

run402-private). When operator email verification is 'pending' and the

gateway returns email_verification.last_challenge.hint, doctor + agent

status render the per-reason hint inline instead of the previous generic

'email not verified' message that gave the operator no actionable signal.

  - cli/lib/doctor.mjs: operator_health gap message reads from new block

  - cli/lib/agent.mjs: 'agent status' merges /agent/v1/operator/status

    email_verification block into the response (best-effort)

  - cli/llms-cli.txt + CHANGELOG: document the new agent-DX surface

Tests: 555/555 pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: MajorTal

CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to `@run402/sdk`, `run402` (CLI), and `run402-mcp`. Versions are kept in lockstep across the three packages in this repo. `@run402/functions` lives in the private gateway monorepo and publishes on its own cadence.
 
+## 2.4.0 — unreleased
+
+Surfaces the v1.56 gateway verification-no-silent-fail bundle ([parent change: `verification-no-silent-fail` in run402-private](https://github.com/kychee-com/run402-private/tree/main/openspec/changes/verification-no-silent-fail)). Closes a class of UX bugs where SES auth-verdict rejections silently failed operator email verification with no signal to the operator. Additive — old clients silently ignore the new fields.
+
+### Added
+
+- **`run402 doctor` surfaces per-attempt verification failure detail** (`cli/lib/doctor.mjs`). When `operator_email` is `pending` and the gateway's `email_verification.last_challenge.hint` is populated, doctor renders it inline: `operator email not verified (1/5 attempts used, 4 remaining): SES reported FAIL on: spf. Fix the corresponding DNS records on <domain> and reply again. 4 more attempts remain.` — instead of the previous generic "email not verified" message that gave the operator no actionable signal.
+- **`run402 agent status` includes `email_verification.last_challenge` block** (`cli/lib/agent.mjs`). Best-effort fetch from `/agent/v1/operator/status` is merged into the response so a single command surfaces the full challenge state: `attempts[]` with per-reason `at`, `from_address`, `reason` (one of `trust_rejected | from_mismatch | threading_miss | code_mismatch`), `sender_trust` verdicts, plus `attempt_count`, `remaining_attempts`, and the gateway-computed `hint`. Older gateways silently keep the original response shape.
+
+### Changed
+
+- **Doctor's `operator_health` check is now strictly more informative** when `email_status !== "verified"`. No behavior change for already-verified operators. The threshold for "warning" status is unchanged; only the message detail improves.
+
+### Out of scope (deliberate carve-out)
+
+- No SDK type changes — `email_verification` is consumed dynamically because the v1.55 SDK already returns the rest of the operator-status response as `unknown`-shaped JSON pass-through, and adding strict types here would force a parallel public-repo edit on every gateway-side field addition. Future work: type the operator-status response shape end-to-end.
+
 ## 2.3.0 — unreleased
 
 Surfaces the v1.49 gateway image-variant pipeline ([run402#392](https://github.com/kychee-com/run402/issues/392), parent change: [`asset-image-variants` in run402-private](https://github.com/kychee-com/run402-private/tree/main/openspec/changes/asset-image-variants)). Additive, non-breaking — old clients silently ignore the new fields.

cli/lib/agent.mjs

@@ -122,7 +122,21 @@ async function status(args = []) {
   allowanceAuthHeaders("/agent/v1/contact/status");
 
   try {
-    const data = await getSdk().admin.getAgentContactStatus();
+    const sdk = getSdk();
+    const data = await sdk.admin.getAgentContactStatus();
+    // v1.56: augment the response with email_verification.last_challenge from
+    // /agent/v1/operator/status so the operator sees per-attempt status
+    // (trust_rejected with which verdicts, attempts remaining, hint) without
+    // a second command. Best-effort — older gateways without the v1.55+ route
+    // skip the augment silently.
+    try {
+      const opStatus = await sdk.admin.getOperatorStatus();
+      if (opStatus && opStatus.email_verification) {
+        data.email_verification = opStatus.email_verification;
+      }
+    } catch {
+      // Older gateway — keep the original response shape.
+    }
     console.log(JSON.stringify(data, null, 2));
   } catch (err) {
     reportSdkError(err);

cli/lib/doctor.mjs

@@ -169,13 +169,25 @@ export async function run(sub, args = []) {
     });
   }
 
-  // 6. Operator health snapshot (v1.55).
+  // 6. Operator health snapshot (v1.55 + v1.56 verification attempt detail).
   try {
     const sdk = getSdk();
     const status = await sdk.admin.getOperatorStatus();
     const gaps = [];
     if (status.operator_contact.email_status !== "verified") {
-      gaps.push(`operator email not verified (${status.operator_contact.email_status}) — run 'run402 agent contact --email ...' then reply to the challenge`);
+      // v1.56: prefer the structured email_verification.last_challenge.hint
+      // over the generic "email not verified" message. The gateway computes
+      // a per-reason remediation hint that's actionable for the operator.
+      const ev = status.email_verification;
+      const ch = ev?.last_challenge;
+      if (ch && ch.hint) {
+        const attemptsLine = ch.attempt_count > 0
+          ? ` (${ch.attempt_count}/${ch.attempt_count + ch.remaining_attempts} attempts used, ${ch.remaining_attempts} remaining)`
+          : "";
+        gaps.push(`operator email not verified${attemptsLine}: ${ch.hint}`);
+      } else {
+        gaps.push(`operator email not verified (${status.operator_contact.email_status}) — run 'run402 agent contact --email ...' then reply to the challenge`);
+      }
     }
     if (status.operator_contact.passkey_status !== "verified") {
       gaps.push("operator passkey not bound — run 'run402 agent passkey enroll' after email verification");

cli/llms-cli.txt

@@ -1254,7 +1254,7 @@ Every invalidate returns `{ deleted, generation, host, path? }`. `generation` is
 ### doctor
 Health + config diagnostics. Agent-DX entrypoint — agents run this first to verify environment before attempting anything else.
 
-- `run402 doctor [--json] [--verbose]` — checks: config dir presence, allowance + rail, keystore wallet count, API base reachability, active tier + lifecycle state. Exit 0 on all-pass, 1 on any failure. `--json` emits `{ ok: boolean, checks: [{ name, status, value?, hint?, message? }] }`.
+- `run402 doctor [--json] [--verbose]` — checks: config dir presence, allowance + rail, keystore wallet count, API base reachability, active tier + lifecycle state, operator health snapshot (binding state + per-attempt verification failure detail since v2.4 / gateway v1.56). Exit 0 on all-pass, 1 on any failure. `--json` emits `{ ok: boolean, checks: [{ name, status, value?, hint?, message? }] }`. When operator email verification is `pending`, the doctor surfaces the per-reason hint from `email_verification.last_challenge.hint` ("publish SPF/DMARC", "reply from registered address", "use Reply button not new message", etc.) along with `attempt_count` / `remaining_attempts` so the operator sees what to fix.
 
 ### dev
 Astro dev wrapper. Loads `.env.local`, verifies `RUN402_PROJECT_ID` + `RUN402_SERVICE_KEY`, then spawns `astro dev` with the env inherited.