Improve operator-first launcher errors and diagnostics labeling

README.md

@@ -49,6 +49,7 @@ Advanced integration controls (collapsible):
 6. Governance install + lease primitives (with explicit `operation_mode`)
 7. Raw response log for deterministic troubleshooting
 8. Wallet session lifecycle controls (manual refresh/revoke + automatic pre-expiry refresh)
+9. Deterministic fail-closed error messaging mapped from backend policy/error codes
 
 Wallet automation helpers remain available in advanced controls:
 

app/app.js

@@ -233,6 +233,56 @@ function logLine(label, payload) {
   log.textContent = line + log.textContent;
 }
 
+const errorCodeHelp = {
+  wallet_session_required: "Session required. Reconnect wallet or refresh session.",
+  wallet_session_invalid: "Session invalid. Reconnect wallet to continue.",
+  wallet_session_expired: "Session expired. Refresh session or reconnect wallet.",
+  wallet_session_revoked: "Session revoked. Reconnect wallet to continue.",
+  wallet_session_mismatch: "Session does not match the active wallet.",
+  membership_required: "EDUT ID must be active before this action.",
+  membership_inactive: "EDUT ID is not active for this wallet.",
+  identity_assurance_insufficient: "This admin action requires on-ramp attestation.",
+  role_insufficient: "Action blocked: org root owner role required.",
+  boundary_mismatch: "Boundary mismatch. Verify org root, principal, and workspace.",
+  entitlement_inactive: "Entitlement is inactive for this action.",
+  entitlement_contract_unconfigured: "Checkout is temporarily unavailable (entitlement contract not configured).",
+  tx_verification_failed: "Transaction not yet verifiable. Wait for chain confirmation and retry.",
+  membership_verification_failed: "Membership proof not yet verifiable. Wait for chain confirmation and retry.",
+  quote_expired: "Quote expired. Request a new quote.",
+  quote_not_found: "Quote not found. Start a new quote flow.",
+  install_token_expired: "Install token expired. Request a new install token.",
+  install_token_not_found: "Install token not found. Request a new install token.",
+  install_token_consumed: "Install token already used. Request a new install token.",
+  chain_verification_unavailable: "Chain verification unavailable. Retry when provider is reachable.",
+};
+
+function friendlyError(err) {
+  const code = String(err?.code || "").trim();
+  if (code && errorCodeHelp[code]) {
+    return {
+      code,
+      message: errorCodeHelp[code],
+    };
+  }
+  const payloadMessage = String(err?.payload?.error || "").trim();
+  const message = payloadMessage || String(err?.message || err || "unknown error");
+  return {
+    code,
+    message,
+  };
+}
+
+function reportActionError(actionID, err) {
+  const normalized = friendlyError(err);
+  setFlowStatus(normalized.message);
+  logLine(`${actionID} error`, {
+    code: normalized.code,
+    message: normalized.message,
+    raw_error: String(err),
+    payload: err?.payload || null,
+  });
+}
+
 function setSummary(id, value) {
   const el = $(id);
   if (!el) return;
@@ -1219,7 +1269,7 @@ function bind(id, handler) {
     try {
       await handler();
     } catch (err) {
-      logLine(`${id} error`, { error: String(err) });
+      reportActionError(id, err);
     }
   });
 }

app/index.html

@@ -89,7 +89,7 @@
       </section>
 
       <details class="panel advanced">
-        <summary>Advanced Integration Controls</summary>
+        <summary>Advanced Integration Controls (Diagnostics)</summary>
         <div class="advanced-body">
           <section class="subpanel">
             <h2>Connection</h2>