diff --git a/apps/desktop/src/electron/ElectronShell.test.ts b/apps/desktop/src/electron/ElectronShell.test.ts
index f5c85769cee..7ab53af0b47 100644
--- a/apps/desktop/src/electron/ElectronShell.test.ts
+++ b/apps/desktop/src/electron/ElectronShell.test.ts
@@ -46,14 +46,49 @@ describe("ElectronShell", () => {
     }).pipe(Effect.provide(ElectronShell.layer)),
   );
 
-  it.effect("returns false when Electron rejects openExternal", () =>
+  it.effect("preserves safe URL context and cause when Electron rejects openExternal", () =>
     Effect.gen(function* () {
-      openExternalMock.mockRejectedValue(new Error("open failed"));
+      const cause = new Error("open failed");
+      openExternalMock.mockRejectedValue(cause);
+      const externalUrl =
+        "HTTPS://user:password@example.com:443/signed-secret-token/path?access_token=secret#fragment";
 
       const electronShell = yield* ElectronShell.ElectronShell;
-      const result = yield* electronShell.openExternal("https://example.com/path");
+      const error = yield* Effect.flip(electronShell.openExternal(externalUrl));
 
-      assert.equal(result, false);
+      assert.instanceOf(error, ElectronShell.ElectronShellOpenExternalError);
+      assert.isTrue(ElectronShell.isElectronShellError(error));
+      assert.strictEqual(error.urlHostname, "example.com");
+      assert.strictEqual(error.urlLength, externalUrl.length);
+      assert.strictEqual(error.urlProtocol, "https:");
+      assert.strictEqual(error.cause, cause);
+      assert.notProperty(error, "externalUrl");
+      assert.notProperty(error, "requestTarget");
+      assert.notMatch(
+        error.message,
+        /user|password|signed-secret-token|path|access_token|secret|fragment/,
+      );
+      assert.notInclude(error.message, cause.message);
+    }).pipe(Effect.provide(ElectronShell.layer)),
+  );
+
+  it.effect("preserves non-sensitive clipboard context and cause", () =>
+    Effect.gen(function* () {
+      const cause = new Error("clipboard failed");
+      writeTextMock.mockImplementation(() => {
+        throw cause;
+      });
+
+      const electronShell = yield* ElectronShell.ElectronShell;
+      const error = yield* Effect.flip(electronShell.copyText("secret text"));
+
+      assert.instanceOf(error, ElectronShell.ElectronShellCopyTextError);
+      assert.isTrue(ElectronShell.isElectronShellError(error));
+      assert.strictEqual(error.textLength, 11);
+      assert.strictEqual(error.cause, cause);
+      assert.include(error.message, "11 characters");
+      assert.notInclude(error.message, "secret text");
+      assert.notInclude(error.message, cause.message);
     }).pipe(Effect.provide(ElectronShell.layer)),
   );
 });
diff --git a/apps/desktop/src/electron/ElectronShell.ts b/apps/desktop/src/electron/ElectronShell.ts
index 316d3138bfa..5fb48df1021 100644
--- a/apps/desktop/src/electron/ElectronShell.ts
+++ b/apps/desktop/src/electron/ElectronShell.ts
@@ -1,12 +1,47 @@
+import { getUrlDiagnostics } from "@t3tools/shared/urlDiagnostics";
 import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
 
 import * as Electron from "electron";
 
 const SAFE_EXTERNAL_PROTOCOLS = new Set(["http:", "https:"]);
 
+export class ElectronShellOpenExternalError extends Schema.TaggedErrorClass<ElectronShellOpenExternalError>()(
+  "ElectronShellOpenExternalError",
+  {
+    urlHostname: Schema.String,
+    urlLength: Schema.Number,
+    urlProtocol: Schema.String,
+    cause: Schema.Defect(),
+  },
+) {
+  override get message(): string {
+    return `Failed to open external URL for ${this.urlHostname} (${this.urlProtocol}, input length ${this.urlLength}).`;
+  }
+}
+
+export class ElectronShellCopyTextError extends Schema.TaggedErrorClass<ElectronShellCopyTextError>()(
+  "ElectronShellCopyTextError",
+  {
+    textLength: Schema.Number,
+    cause: Schema.Defect(),
+  },
+) {
+  override get message(): string {
+    return `Failed to copy ${this.textLength} characters to the clipboard.`;
+  }
+}
+
+export const ElectronShellError = Schema.Union([
+  ElectronShellOpenExternalError,
+  ElectronShellCopyTextError,
+]);
+export type ElectronShellError = typeof ElectronShellError.Type;
+export const isElectronShellError = Schema.is(ElectronShellError);
+
 export function parseSafeExternalUrl(rawUrl: unknown): Option.Option<string> {
   if (typeof rawUrl !== "string") {
     return Option.none();
@@ -20,29 +55,46 @@ export function parseSafeExternalUrl(rawUrl: unknown): Option.Option<string> {
   }
 }
 
+function describeExternalUrl(externalUrl: string, inputLength: number) {
+  const diagnostics = getUrlDiagnostics(externalUrl);
+  return {
+    urlHostname: diagnostics.hostname ?? "",
+    urlLength: inputLength,
+    urlProtocol: diagnostics.protocol ?? "",
+  };
+}
+
 export class ElectronShell extends Context.Service<
   ElectronShell,
   {
-    readonly openExternal: (rawUrl: unknown) => Effect.Effect<boolean>;
-    readonly copyText: (text: string) => Effect.Effect<void>;
+    readonly openExternal: (
+      rawUrl: unknown,
+    ) => Effect.Effect<boolean, ElectronShellOpenExternalError>;
+    readonly copyText: (text: string) => Effect.Effect<void, ElectronShellCopyTextError>;
   }
 >()("@t3tools/desktop/electron/ElectronShell") {}
 
 export const make = ElectronShell.of({
-  openExternal: (rawUrl) =>
-    Option.match(parseSafeExternalUrl(rawUrl), {
+  openExternal: (rawUrl) => {
+    const inputLength = typeof rawUrl === "string" ? rawUrl.length : 0;
+
+    return Option.match(parseSafeExternalUrl(rawUrl), {
       onNone: () => Effect.succeed(false),
       onSome: (externalUrl) =>
-        Effect.promise(() =>
-          Electron.shell.openExternal(externalUrl).then(
-            () => true,
-            () => false,
-          ),
-        ),
-    }),
+        Effect.tryPromise({
+          try: () => Electron.shell.openExternal(externalUrl),
+          catch: (cause) =>
+            new ElectronShellOpenExternalError({
+              ...describeExternalUrl(externalUrl, inputLength),
+              cause,
+            }),
+        }).pipe(Effect.as(true)),
+    });
+  },
   copyText: (text) =>
-    Effect.sync(() => {
-      Electron.clipboard.writeText(text);
+    Effect.try({
+      try: () => Electron.clipboard.writeText(text),
+      catch: (cause) => new ElectronShellCopyTextError({ textLength: text.length, cause }),
     }),
 });
 
diff --git a/apps/desktop/src/ipc/channels.ts b/apps/desktop/src/ipc/channels.ts
index cc2a92ca8fd..477d7500fe4 100644
--- a/apps/desktop/src/ipc/channels.ts
+++ b/apps/desktop/src/ipc/channels.ts
@@ -32,7 +32,6 @@ export const GET_SERVER_EXPOSURE_STATE_CHANNEL = "desktop:get-server-exposure-st
 export const SET_SERVER_EXPOSURE_MODE_CHANNEL = "desktop:set-server-exposure-mode";
 export const SET_TAILSCALE_SERVE_ENABLED_CHANNEL = "desktop:set-tailscale-serve-enabled";
 export const GET_ADVERTISED_ENDPOINTS_CHANNEL = "desktop:get-advertised-endpoints";
-export const SSH_PASSWORD_PROMPT_CANCELLED_RESULT = "ssh-password-prompt-cancelled";
 export const PREVIEW_CREATE_TAB_CHANNEL = "desktop:preview-create-tab";
 export const PREVIEW_CLOSE_TAB_CHANNEL = "desktop:preview-close-tab";
 export const PREVIEW_REGISTER_WEBVIEW_CHANNEL = "desktop:preview-register-webview";
diff --git a/apps/desktop/src/ipc/methods/sshEnvironment.test.ts b/apps/desktop/src/ipc/methods/sshEnvironment.test.ts
index fa53486d5e2..88eb7c42782 100644
--- a/apps/desktop/src/ipc/methods/sshEnvironment.test.ts
+++ b/apps/desktop/src/ipc/methods/sshEnvironment.test.ts
@@ -1,16 +1,28 @@
 import { assert, describe, it } from "@effect/vitest";
-import { SshHttpBridgeError } from "@t3tools/ssh/errors";
+import {
+  DesktopSshEnvironmentEnsureResultSchema,
+  DesktopSshPasswordPromptCancellationError,
+} from "@t3tools/contracts";
+import { SshHttpBridgeError, SshPasswordPromptError } from "@t3tools/ssh/errors";
 import * as Cause from "effect/Cause";
 import * as Effect from "effect/Effect";
 import * as Exit from "effect/Exit";
 import * as Layer from "effect/Layer";
 import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
 import { HttpClient, HttpClientRequest, HttpClientResponse } from "effect/unstable/http";
 
 import {
   DesktopSshEnvironmentRequestError,
+  ensureSshEnvironment,
   fetchSshEnvironmentDescriptor,
 } from "./sshEnvironment.ts";
+import * as DesktopSshEnvironment from "../../ssh/DesktopSshEnvironment.ts";
+import * as DesktopSshPasswordPrompts from "../../ssh/DesktopSshPasswordPrompts.ts";
+
+const decodeDesktopSshEnvironmentEnsureResult = Schema.decodeUnknownEffect(
+  DesktopSshEnvironmentEnsureResultSchema,
+);
 
 function jsonResponse(request: HttpClientRequest.HttpClientRequest, body: unknown, status = 200) {
   return HttpClientResponse.fromWeb(
@@ -34,6 +46,44 @@ function makeHttpClientLayer(
 }
 
 describe("SSH environment IPC", () => {
+  it.effect("encodes password prompt cancellations with structured context and their cause", () => {
+    const promptCause = new DesktopSshPasswordPrompts.DesktopSshPromptWindowClosedError({
+      requestId: "prompt-1",
+      destination: "developer@devbox.example.test",
+    });
+    const cause = new SshPasswordPromptError({
+      message: promptCause.message,
+      cause: promptCause,
+    });
+    const layer = Layer.succeed(
+      DesktopSshEnvironment.DesktopSshEnvironment,
+      DesktopSshEnvironment.DesktopSshEnvironment.of({
+        discoverHosts: () => Effect.die("unexpected host discovery"),
+        ensureEnvironment: () => Effect.fail(cause),
+        disconnectEnvironment: () => Effect.die("unexpected disconnect"),
+      }),
+    );
+
+    return Effect.gen(function* () {
+      const encoded = yield* ensureSshEnvironment.handler({
+        target: {
+          alias: "devbox",
+          hostname: "devbox.example.test",
+          username: "developer",
+          port: 22,
+        },
+      });
+      const error = yield* decodeDesktopSshEnvironmentEnsureResult(encoded);
+
+      assert.instanceOf(error, DesktopSshPasswordPromptCancellationError);
+      assert.equal(error.reason, "window-closed");
+      assert.equal(error.requestId, "prompt-1");
+      assert.equal(error.destination, "developer@devbox.example.test");
+      assert.instanceOf(error.cause, Error);
+      assert.instanceOf(error.cause.cause, Error);
+    }).pipe(Effect.provide(layer));
+  });
+
   it.effect("fetches and decodes the remote environment descriptor", () => {
     const requestUrls: string[] = [];
     const layer = makeHttpClientLayer((request) =>
diff --git a/apps/desktop/src/ipc/methods/sshEnvironment.ts b/apps/desktop/src/ipc/methods/sshEnvironment.ts
index 9c9af2a4e2b..69a3c32b1b5 100644
--- a/apps/desktop/src/ipc/methods/sshEnvironment.ts
+++ b/apps/desktop/src/ipc/methods/sshEnvironment.ts
@@ -2,7 +2,7 @@ import {
   bootstrapRemoteBearerSession,
   fetchRemoteSessionState,
   issueRemoteWebSocketTicket,
-  RemoteEnvironmentAuthUndeclaredStatusError,
+  isRemoteEnvironmentAuthUndeclaredStatusError,
   type RemoteEnvironmentAuthError,
 } from "@t3tools/client-runtime/authorization";
 import { fetchRemoteEnvironmentDescriptor } from "@t3tools/client-runtime/environment";
@@ -15,7 +15,7 @@ import {
   DesktopSshEnvironmentEnsureResultSchema,
   DesktopSshEnvironmentTargetSchema,
   DesktopSshHttpBaseUrlInputSchema,
-  DesktopSshPasswordPromptCancelledType,
+  DesktopSshPasswordPromptCancellationError,
   DesktopSshPasswordPromptResolutionInputSchema,
   ExecutionEnvironmentDescriptor,
   EnvironmentInternalError,
@@ -45,6 +45,13 @@ type DesktopSshEnvironmentRequestOperation =
 
 type DesktopSshEnvironmentRequestCause = RemoteEnvironmentAuthError | SshHttpBridgeError;
 
+const desktopSshPasswordPromptCancellationReasons = {
+  DesktopSshPromptCancelledError: "user-cancelled",
+  DesktopSshPromptWindowClosedError: "window-closed",
+  DesktopSshPromptServiceStoppedError: "service-stopped",
+  DesktopSshPromptTimedOutError: "timed-out",
+} as const;
+
 const isEnvironmentAuthInvalidError = Schema.is(EnvironmentAuthInvalidError);
 const isEnvironmentInternalError = Schema.is(EnvironmentInternalError);
 const isEnvironmentOperationForbiddenError = Schema.is(EnvironmentOperationForbiddenError);
@@ -52,10 +59,7 @@ const isEnvironmentRequestInvalidError = Schema.is(EnvironmentRequestInvalidErro
 const isEnvironmentScopeRequiredError = Schema.is(EnvironmentScopeRequiredError);
 
 function readSshHttpStatus(cause: DesktopSshEnvironmentRequestCause): number | null {
-  if (
-    cause instanceof RemoteEnvironmentAuthUndeclaredStatusError ||
-    cause instanceof SshHttpBridgeError
-  ) {
+  if (isRemoteEnvironmentAuthUndeclaredStatusError(cause) || cause instanceof SshHttpBridgeError) {
     return cause.status ?? null;
   }
   if (isEnvironmentRequestInvalidError(cause)) {
@@ -127,14 +131,19 @@ export const ensureSshEnvironment = DesktopIpc.makeIpcMethod({
   }) {
     const sshEnvironment = yield* DesktopSshEnvironment.DesktopSshEnvironment;
     return yield* sshEnvironment.ensureEnvironment(target, options).pipe(
-      Effect.catch((error) =>
-        DesktopSshEnvironment.isDesktopSshPasswordPromptCancellation(error)
-          ? Effect.succeed({
-              type: DesktopSshPasswordPromptCancelledType,
-              message: error.message,
-            })
-          : Effect.fail(error),
-      ),
+      Effect.catchTags({
+        SshPasswordPromptError: (error) =>
+          DesktopSshEnvironment.isDesktopSshPasswordPromptCancellation(error)
+            ? Effect.succeed(
+                new DesktopSshPasswordPromptCancellationError({
+                  reason: desktopSshPasswordPromptCancellationReasons[error.cause._tag],
+                  requestId: error.cause.requestId,
+                  destination: error.cause.destination,
+                  cause: error,
+                }),
+              )
+            : Effect.fail(error),
+      }),
     );
   }),
 });
diff --git a/apps/desktop/src/ipc/methods/window.test.ts b/apps/desktop/src/ipc/methods/window.test.ts
new file mode 100644
index 00000000000..609d3e30a13
--- /dev/null
+++ b/apps/desktop/src/ipc/methods/window.test.ts
@@ -0,0 +1,34 @@
+import { assert, describe, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Logger from "effect/Logger";
+
+import { openExternal } from "./window.ts";
+import * as ElectronShell from "../../electron/ElectronShell.ts";
+
+describe("window IPC", () => {
+  it.effect("returns false when Electron rejects an external URL", () => {
+    const url = "https://example.com/path";
+    const error = new ElectronShell.ElectronShellOpenExternalError({
+      urlHostname: "example.com",
+      urlLength: url.length,
+      urlProtocol: "https:",
+      cause: new Error("open failed"),
+    });
+    const layer = Layer.mergeAll(
+      Layer.succeed(
+        ElectronShell.ElectronShell,
+        ElectronShell.ElectronShell.of({
+          openExternal: () => Effect.fail(error),
+          copyText: () => Effect.void,
+        }),
+      ),
+      Logger.layer([], { mergeWithExisting: false }),
+    );
+
+    return Effect.gen(function* () {
+      const opened = yield* openExternal.handler(url);
+      assert.equal(opened, false);
+    }).pipe(Effect.provide(layer));
+  });
+});
diff --git a/apps/desktop/src/ipc/methods/window.ts b/apps/desktop/src/ipc/methods/window.ts
index 3cb705d0361..b638b77e6a3 100644
--- a/apps/desktop/src/ipc/methods/window.ts
+++ b/apps/desktop/src/ipc/methods/window.ts
@@ -7,6 +7,7 @@ import {
 } from "@t3tools/contracts";
 import * as Effect from "effect/Effect";
 import * as Option from "effect/Option";
+import * as Redacted from "effect/Redacted";
 import * as Schema from "effect/Schema";
 
 import * as DesktopBackendManager from "../../backend/DesktopBackendManager.ts";
@@ -141,6 +142,19 @@ export const openExternal = DesktopIpc.makeIpcMethod({
   result: Schema.Boolean,
   handler: Effect.fn("desktop.ipc.window.openExternal")(function* (url) {
     const shell = yield* ElectronShell.ElectronShell;
-    return yield* shell.openExternal(url);
+    return yield* shell.openExternal(url).pipe(
+      Effect.catchTag("ElectronShellOpenExternalError", (error) =>
+        Effect.logWarning(error.message).pipe(
+          Effect.annotateLogs({
+            error: Redacted.make(error, { label: error._tag }),
+            "error.type": error._tag,
+            "desktop.external_url.hostname": error.urlHostname,
+            "desktop.external_url.input_length": error.urlLength,
+            "desktop.external_url.protocol": error.urlProtocol,
+          }),
+          Effect.as(false),
+        ),
+      ),
+    );
   }),
 });
diff --git a/apps/desktop/src/preload.ts b/apps/desktop/src/preload.ts
index 6f126f41334..5e99b92f0f6 100644
--- a/apps/desktop/src/preload.ts
+++ b/apps/desktop/src/preload.ts
@@ -1,28 +1,31 @@
-import type {
-  DesktopBridge,
-  DesktopPreviewPointerEvent,
-  DesktopPreviewRecordingFrame,
-  DesktopPreviewTabState,
+import {
+  DesktopSshPasswordPromptCancellationError,
+  DesktopSshPasswordPromptCancellationErrorTag,
+  type DesktopBridge,
+  type DesktopPreviewPointerEvent,
+  type DesktopPreviewRecordingFrame,
+  type DesktopPreviewTabState,
 } from "@t3tools/contracts";
 import { exposeClerkBridge } from "@clerk/electron/preload";
 import { contextBridge, ipcRenderer } from "electron";
+import * as Schema from "effect/Schema";
 
 import * as IpcChannels from "./ipc/channels.ts";
 
 exposeClerkBridge({ passkeys: true });
 
+const decodeDesktopSshPasswordPromptCancellationError = Schema.decodeUnknownSync(
+  DesktopSshPasswordPromptCancellationError,
+);
+
 function unwrapEnsureSshEnvironmentResult(result: unknown) {
   if (
     typeof result === "object" &&
     result !== null &&
-    "type" in result &&
-    result.type === IpcChannels.SSH_PASSWORD_PROMPT_CANCELLED_RESULT
+    "_tag" in result &&
+    result._tag === DesktopSshPasswordPromptCancellationErrorTag
   ) {
-    const message =
-      "message" in result && typeof result.message === "string"
-        ? result.message
-        : "SSH authentication cancelled.";
-    throw new Error(message);
+    throw decodeDesktopSshPasswordPromptCancellationError(result);
   }
   return result as Awaited<ReturnType<DesktopBridge["ensureSshEnvironment"]>>;
 }
diff --git a/apps/desktop/src/ssh/DesktopSshEnvironment.ts b/apps/desktop/src/ssh/DesktopSshEnvironment.ts
index 31e84ae995e..495d5ea9c1a 100644
--- a/apps/desktop/src/ssh/DesktopSshEnvironment.ts
+++ b/apps/desktop/src/ssh/DesktopSshEnvironment.ts
@@ -75,7 +75,9 @@ function discoverDesktopSshHostsEffect(input?: { readonly homeDir?: string }) {
 
 export function isDesktopSshPasswordPromptCancellation(
   error: unknown,
-): error is SshPasswordPromptError {
+): error is SshPasswordPromptError & {
+  readonly cause: DesktopSshPasswordPrompts.DesktopSshPasswordPromptCancellation;
+} {
   return (
     error instanceof SshPasswordPromptError &&
     DesktopSshPasswordPrompts.isDesktopSshPasswordPromptCancellation(error.cause)
diff --git a/apps/desktop/src/window/DesktopWindow.ts b/apps/desktop/src/window/DesktopWindow.ts
index e6cfce3c54f..cf4f2b4e556 100644
--- a/apps/desktop/src/window/DesktopWindow.ts
+++ b/apps/desktop/src/window/DesktopWindow.ts
@@ -226,7 +226,9 @@ export const make = Effect.gen(function* () {
           {
             label: "Copy Link",
             click: () => {
-              void runPromise(electronShell.copyText(params.linkURL));
+              void runPromise(
+                electronShell.copyText(params.linkURL).pipe(Effect.ignore({ log: true })),
+              );
             },
           },
           { type: "separator" },
@@ -253,7 +255,7 @@ export const make = Effect.gen(function* () {
 
     window.webContents.setWindowOpenHandler(({ url }) => {
       if (Option.isSome(ElectronShell.parseSafeExternalUrl(url))) {
-        void runPromise(electronShell.openExternal(url));
+        void runPromise(electronShell.openExternal(url).pipe(Effect.ignore({ log: true })));
       }
       return { action: "deny" };
     });
@@ -269,7 +271,7 @@ export const make = Effect.gen(function* () {
 
       event.preventDefault();
       if (Option.isSome(ElectronShell.parseSafeExternalUrl(url))) {
-        void runPromise(electronShell.openExternal(url));
+        void runPromise(electronShell.openExternal(url).pipe(Effect.ignore({ log: true })));
       }
     });
 
diff --git a/apps/mobile/src/connection/catalog-store.ts b/apps/mobile/src/connection/catalog-store.ts
index b5bda400670..737538e4530 100644
--- a/apps/mobile/src/connection/catalog-store.ts
+++ b/apps/mobile/src/connection/catalog-store.ts
@@ -3,7 +3,10 @@ import {
   type ConnectionCatalogDocument as ConnectionCatalogDocumentType,
   EMPTY_CONNECTION_CATALOG_DOCUMENT,
 } from "@t3tools/client-runtime/platform";
-import { ConnectionTransientError } from "@t3tools/client-runtime/connection";
+import {
+  ConnectionStorageOperationError,
+  ConnectionTransientError,
+} from "@t3tools/client-runtime/connection";
 import * as Effect from "effect/Effect";
 import * as Option from "effect/Option";
 import * as Ref from "effect/Ref";
@@ -15,30 +18,38 @@ import { migrateLegacyConnectionCatalog } from "./migration";
 export const CONNECTION_CATALOG_KEY = "t3code.connection-catalog.v1";
 export const LEGACY_CONNECTIONS_KEY = "t3code.connections";
 
-function catalogError(operation: string, cause: unknown) {
-  return new ConnectionTransientError({
-    reason: "remote-unavailable",
-    detail: `Could not ${operation} the local connection catalog: ${String(cause)}`,
-  });
-}
+const ConnectionCatalogDocumentJson = Schema.fromJsonString(ConnectionCatalogDocument);
+const decodeConnectionCatalogDocument = Schema.decodeUnknownEffect(ConnectionCatalogDocumentJson);
+const encodeConnectionCatalogDocument = Schema.encodeEffect(ConnectionCatalogDocumentJson);
 
 const decodeCatalog = Effect.fn("mobile.connectionStorage.decodeCatalog")(function* (raw: string) {
-  const parsed = yield* Effect.try({
-    try: () => JSON.parse(raw) as unknown,
-    catch: (cause) => catalogError("decode", cause),
-  });
-  return yield* Effect.fromResult(
-    Schema.decodeUnknownResult(ConnectionCatalogDocument)(parsed),
-  ).pipe(Effect.mapError((cause) => catalogError("decode", cause)));
+  return yield* decodeConnectionCatalogDocument(raw).pipe(
+    Effect.mapError((cause) =>
+      ConnectionTransientError.fromStorageFailure(
+        new ConnectionStorageOperationError({
+          operation: "decode",
+          backend: "schema",
+          cause,
+        }),
+      ),
+    ),
+  );
 });
 
 const encodeCatalog = Effect.fn("mobile.connectionStorage.encodeCatalog")(function* (
   catalog: ConnectionCatalogDocumentType,
 ) {
-  const encoded = yield* Effect.fromResult(
-    Schema.encodeUnknownResult(ConnectionCatalogDocument)(catalog),
-  ).pipe(Effect.mapError((cause) => catalogError("encode", cause)));
-  return JSON.stringify(encoded);
+  return yield* encodeConnectionCatalogDocument(catalog).pipe(
+    Effect.mapError((cause) =>
+      ConnectionTransientError.fromStorageFailure(
+        new ConnectionStorageOperationError({
+          operation: "encode",
+          backend: "schema",
+          cause,
+        }),
+      ),
+    ),
+  );
 });
 
 interface CatalogStore {
@@ -66,12 +77,21 @@ export const makeCatalogStore = Effect.fn("mobile.connectionStorage.makeCatalogS
       legacyRaw === null || legacyRaw.trim() === ""
         ? EMPTY_CONNECTION_CATALOG_DOCUMENT
         : yield* migrateLegacyConnectionCatalog(legacyRaw).pipe(
-            Effect.mapError((cause) => catalogError("migrate", cause)),
-            Effect.catch((error) =>
-              Effect.logWarning("Discarding corrupt legacy mobile connections", error).pipe(
-                Effect.as(EMPTY_CONNECTION_CATALOG_DOCUMENT),
+            Effect.mapError((cause) =>
+              ConnectionTransientError.fromStorageFailure(
+                new ConnectionStorageOperationError({
+                  operation: "migrate",
+                  backend: "legacy-migration",
+                  cause,
+                }),
               ),
             ),
+            Effect.catchTags({
+              ConnectionTransientError: (error) =>
+                Effect.logWarning("Discarding corrupt legacy mobile connections", error).pipe(
+                  Effect.as(EMPTY_CONNECTION_CATALOG_DOCUMENT),
+                ),
+            }),
           );
     if (legacyRaw !== null && legacyRaw.trim() !== "") {
       const encoded = yield* encodeCatalog(catalog);
@@ -90,12 +110,13 @@ export const makeCatalogStore = Effect.fn("mobile.connectionStorage.makeCatalogS
     let catalog: ConnectionCatalogDocumentType;
     if (raw !== null && raw.trim() !== "") {
       catalog = yield* decodeCatalog(raw).pipe(
-        Effect.catch((error) =>
-          Effect.logWarning("Discarding corrupt mobile connection catalog", error).pipe(
-            Effect.andThen(storage.deleteItem(CONNECTION_CATALOG_KEY)),
-            Effect.andThen(loadLegacyCatalog()),
-          ),
-        ),
+        Effect.catchTags({
+          ConnectionTransientError: (error) =>
+            Effect.logWarning("Discarding corrupt mobile connection catalog", error).pipe(
+              Effect.andThen(storage.deleteItem(CONNECTION_CATALOG_KEY)),
+              Effect.andThen(loadLegacyCatalog()),
+            ),
+        }),
       );
     } else {
       catalog = yield* loadLegacyCatalog();
diff --git a/apps/mobile/src/connection/migration.test.ts b/apps/mobile/src/connection/migration.test.ts
index 5cb17bd5bf7..a3bd6359315 100644
--- a/apps/mobile/src/connection/migration.test.ts
+++ b/apps/mobile/src/connection/migration.test.ts
@@ -2,7 +2,7 @@ import { describe, expect, it } from "@effect/vitest";
 import { EnvironmentId } from "@t3tools/contracts";
 import * as Effect from "effect/Effect";
 
-import { migrateLegacyConnectionCatalog } from "./migration";
+import { LegacyConnectionMigrationError, migrateLegacyConnectionCatalog } from "./migration";
 
 describe("migrateLegacyConnectionCatalog", () => {
   it.effect("migrates bearer and relay-managed connections into the new catalog", () =>
@@ -75,4 +75,28 @@ describe("migrateLegacyConnectionCatalog", () => {
       expect(catalog.targets).toEqual([]);
     }),
   );
+
+  it.effect("preserves parse failures with a stable structural error", () =>
+    Effect.gen(function* () {
+      const error = yield* migrateLegacyConnectionCatalog("{not-json").pipe(Effect.flip);
+
+      expect(error).toBeInstanceOf(LegacyConnectionMigrationError);
+      expect(error.stage).toBe("parse");
+      expect(error.cause).toBeInstanceOf(SyntaxError);
+      expect(error.message).toBe("Could not parse the legacy mobile connection catalog.");
+    }),
+  );
+
+  it.effect("distinguishes catalog decoding failures", () =>
+    Effect.gen(function* () {
+      const error = yield* migrateLegacyConnectionCatalog('{"connections":"invalid"}').pipe(
+        Effect.flip,
+      );
+
+      expect(error).toBeInstanceOf(LegacyConnectionMigrationError);
+      expect(error.stage).toBe("decode");
+      expect(error.cause).toBeDefined();
+      expect(error.message).toBe("Could not decode the legacy mobile connection catalog.");
+    }),
+  );
 });
diff --git a/apps/mobile/src/connection/migration.ts b/apps/mobile/src/connection/migration.ts
index 6f324c9ff15..65f2fccd1d3 100644
--- a/apps/mobile/src/connection/migration.ts
+++ b/apps/mobile/src/connection/migration.ts
@@ -36,9 +36,14 @@ const decodeLegacyConnectionDocument = Schema.decodeUnknownEffect(LegacyConnecti
 export class LegacyConnectionMigrationError extends Schema.TaggedErrorClass<LegacyConnectionMigrationError>()(
   "LegacyConnectionMigrationError",
   {
-    message: Schema.String,
+    stage: Schema.Literals(["parse", "decode"]),
+    cause: Schema.Defect(),
   },
-) {}
+) {
+  override get message(): string {
+    return `Could not ${this.stage} the legacy mobile connection catalog.`;
+  }
+}
 
 function isRelayManaged(connection: typeof LegacySavedRemoteConnection.Type): boolean {
   return connection.relayManaged === true || connection.authenticationMethod === "dpop";
@@ -92,18 +97,10 @@ export const migrateLegacyConnectionCatalog = Effect.fn(
 )(function* (raw: string) {
   const parsed = yield* Effect.try({
     try: () => JSON.parse(raw) as unknown,
-    catch: (cause) =>
-      new LegacyConnectionMigrationError({
-        message: `Could not parse the legacy mobile connection catalog: ${String(cause)}`,
-      }),
+    catch: (cause) => new LegacyConnectionMigrationError({ stage: "parse", cause }),
   });
   const legacy = yield* decodeLegacyConnectionDocument(parsed).pipe(
-    Effect.mapError(
-      (cause) =>
-        new LegacyConnectionMigrationError({
-          message: `Could not decode the legacy mobile connection catalog: ${String(cause)}`,
-        }),
-    ),
+    Effect.mapError((cause) => new LegacyConnectionMigrationError({ stage: "decode", cause })),
   );
 
   return (legacy.connections ?? []).reduce(migrateConnection, EMPTY_CONNECTION_CATALOG_DOCUMENT);
diff --git a/apps/mobile/src/connection/platform.ts b/apps/mobile/src/connection/platform.ts
index 769632a8fcb..0e33f2f0ec7 100644
--- a/apps/mobile/src/connection/platform.ts
+++ b/apps/mobile/src/connection/platform.ts
@@ -100,7 +100,8 @@ const capabilitiesLayer = Layer.succeedContext(
             (error) =>
               new ConnectionTransientError({
                 reason: "network",
-                detail: error.message,
+                detail: "Could not read the T3 Cloud session token.",
+                cause: error,
               }),
           ),
         );
@@ -126,7 +127,8 @@ const capabilitiesLayer = Layer.succeedContext(
           catch: (cause) =>
             new ConnectionTransientError({
               reason: "remote-unavailable",
-              detail: `Could not load the mobile device identity: ${String(cause)}`,
+              detail: "Could not load the mobile device identity.",
+              cause,
             }),
         }).pipe(Effect.map(Option.some)),
       }),
diff --git a/apps/mobile/src/connection/storage.ts b/apps/mobile/src/connection/storage.ts
index 276ea3c5c08..ba894c7d17d 100644
--- a/apps/mobile/src/connection/storage.ts
+++ b/apps/mobile/src/connection/storage.ts
@@ -10,6 +10,7 @@ import {
 } from "@t3tools/client-runtime/platform";
 import { TokenStore } from "@t3tools/client-runtime/authorization";
 import {
+  ConnectionStorageOperationError,
   ConnectionTransientError,
   CredentialStore,
   ProfileStore,
@@ -54,29 +55,11 @@ const LegacyStoredShellSnapshot = Schema.Struct({
   snapshotReceivedAt: Schema.String,
   snapshot: OrchestrationShellSnapshot,
 });
-
-function catalogError(operation: string, cause: unknown) {
-  return new ConnectionTransientError({
-    reason: "remote-unavailable",
-    detail: `Could not ${operation} the local connection catalog: ${String(cause)}`,
-  });
-}
-
-function shellPersistenceError(
-  operation:
-    | "load-shell"
-    | "save-shell"
-    | "load-thread"
-    | "save-thread"
-    | "remove-thread"
-    | "clear-environment",
-  cause: unknown,
-) {
-  return new ConnectionPersistenceError({
-    operation,
-    message: `Could not ${operation.replaceAll("-", " ")}: ${String(cause)}`,
-  });
-}
+const decodeStoredShellSnapshot = Schema.decodeUnknownEffect(StoredShellSnapshot);
+const encodeStoredShellSnapshot = Schema.encodeEffect(StoredShellSnapshot);
+const decodeStoredThreadSnapshot = Schema.decodeUnknownEffect(StoredThreadSnapshot);
+const encodeStoredThreadSnapshot = Schema.encodeEffect(StoredThreadSnapshot);
+const decodeLegacyStoredShellSnapshot = Schema.decodeUnknownEffect(LegacyStoredShellSnapshot);
 
 function threadSnapshotFileName(threadId: ThreadId): string {
   return `${encodeURIComponent(threadId)}.json`;
@@ -100,7 +83,14 @@ const threadSnapshotDirectory = Effect.fn("mobile.connectionStorage.threadSnapsh
         }
         return directory;
       },
-      catch: (cause) => shellPersistenceError(operation, cause),
+      catch: (cause) =>
+        new ConnectionPersistenceError({
+          operation,
+          stage: "resolve",
+          resource: "thread-cache",
+          environmentId,
+          cause,
+        }),
     });
   },
 );
@@ -110,38 +100,63 @@ const threadSnapshotFile = Effect.fn("mobile.connectionStorage.threadSnapshotFil
   threadId: ThreadId,
   operation: "load-thread" | "save-thread" | "remove-thread",
 ) {
-  const { File } = yield* Effect.promise(() => import("expo-file-system"));
-  return new File(
-    yield* threadSnapshotDirectory(environmentId, operation),
-    threadSnapshotFileName(threadId),
-  );
-});
-
-function targetPersistenceError(
-  operation: "list-targets" | "register-connection" | "remove-connection",
-  error: ConnectionTransientError,
-) {
-  return new ConnectionPersistenceError({
-    operation,
-    message: error.message,
+  const directory = yield* threadSnapshotDirectory(environmentId, operation);
+  return yield* Effect.tryPromise({
+    try: async () => {
+      const { File } = await import("expo-file-system");
+      return new File(directory, threadSnapshotFileName(threadId));
+    },
+    catch: (cause) =>
+      new ConnectionPersistenceError({
+        operation,
+        stage: "resolve",
+        resource: "thread-cache",
+        environmentId,
+        threadId,
+        cause,
+      }),
   });
-}
+});
 
 const secureCatalogStorage: SecureCatalogStorage = {
   getItem: (key) =>
     Effect.tryPromise({
       try: () => SecureStore.getItemAsync(key),
-      catch: (cause) => catalogError("load", cause),
+      catch: (cause) =>
+        ConnectionTransientError.fromStorageFailure(
+          new ConnectionStorageOperationError({
+            operation: "load",
+            backend: "mobile-secure-storage",
+            key,
+            cause,
+          }),
+        ),
     }),
   setItem: (key, value) =>
     Effect.tryPromise({
       try: () => SecureStore.setItemAsync(key, value),
-      catch: (cause) => catalogError("save", cause),
+      catch: (cause) =>
+        ConnectionTransientError.fromStorageFailure(
+          new ConnectionStorageOperationError({
+            operation: "save",
+            backend: "mobile-secure-storage",
+            key,
+            cause,
+          }),
+        ),
     }),
   deleteItem: (key) =>
     Effect.tryPromise({
       try: () => SecureStore.deleteItemAsync(key),
-      catch: (cause) => catalogError("delete", cause),
+      catch: (cause) =>
+        ConnectionTransientError.fromStorageFailure(
+          new ConnectionStorageOperationError({
+            operation: "delete",
+            backend: "mobile-secure-storage",
+            key,
+            cause,
+          }),
+        ),
     }),
 };
 
@@ -156,6 +171,8 @@ const shellSnapshotFileInDirectory = Effect.fn(
   operation: "load-shell" | "save-shell" | "clear-environment",
   directoryName: string,
 ) {
+  const resource =
+    directoryName === LEGACY_SHELL_SNAPSHOT_CACHE_DIRECTORY ? "legacy-shell-cache" : "shell-cache";
   return yield* Effect.tryPromise({
     try: async () => {
       const { Directory, File, Paths } = await import("expo-file-system");
@@ -163,7 +180,14 @@ const shellSnapshotFileInDirectory = Effect.fn(
       directory.create({ idempotent: true, intermediates: true });
       return new File(directory, shellSnapshotFileName(environmentId));
     },
-    catch: (cause) => shellPersistenceError(operation, cause),
+    catch: (cause) =>
+      new ConnectionPersistenceError({
+        operation,
+        stage: "resolve",
+        resource,
+        environmentId,
+        cause,
+      }),
   });
 });
 
@@ -184,18 +208,45 @@ export const connectionStorageLayer = Layer.effectContext(
     const targetStore = ConnectionTargetStore.of({
       list: catalog.read.pipe(
         Effect.map((document) => document.targets),
-        Effect.mapError((error) => targetPersistenceError("list-targets", error)),
+        Effect.mapError((cause) =>
+          ConnectionPersistenceError.fromStorageFailure({
+            operation: "list-targets",
+            fallbackStage: "read",
+            resource: "connection-catalog",
+            cause,
+          }),
+        ),
       ),
     });
     const registrationStore = ConnectionRegistrationStore.of({
       register: (registration) =>
         catalog
           .update((document) => registerConnectionInCatalog(document, registration))
-          .pipe(Effect.mapError((error) => targetPersistenceError("register-connection", error))),
+          .pipe(
+            Effect.mapError((cause) =>
+              ConnectionPersistenceError.fromStorageFailure({
+                operation: "register-connection",
+                fallbackStage: "write",
+                resource: "connection-catalog",
+                environmentId: registration.target.environmentId,
+                cause,
+              }),
+            ),
+          ),
       remove: (target) =>
         catalog
           .update((document) => removeConnectionFromCatalog(document, target))
-          .pipe(Effect.mapError((error) => targetPersistenceError("remove-connection", error))),
+          .pipe(
+            Effect.mapError((cause) =>
+              ConnectionPersistenceError.fromStorageFailure({
+                operation: "remove-connection",
+                fallbackStage: "write",
+                resource: "connection-catalog",
+                environmentId: target.environmentId,
+                cause,
+              }),
+            ),
+          ),
     });
     const profileStore = ProfileStore.make({
       get: (connectionId) =>
@@ -283,15 +334,38 @@ export const connectionStorageLayer = Layer.effectContext(
           if (file.exists) {
             const raw = yield* Effect.tryPromise({
               try: () => file.text(),
-              catch: (cause) => shellPersistenceError("load-shell", cause),
+              catch: (cause) =>
+                new ConnectionPersistenceError({
+                  operation: "load-shell",
+                  stage: "read",
+                  resource: "shell-cache",
+                  environmentId,
+                  cause,
+                }),
             });
             const parsed = yield* Effect.try({
               try: () => JSON.parse(raw) as unknown,
-              catch: (cause) => shellPersistenceError("load-shell", cause),
+              catch: (cause) =>
+                new ConnectionPersistenceError({
+                  operation: "load-shell",
+                  stage: "parse",
+                  resource: "shell-cache",
+                  environmentId,
+                  cause,
+                }),
             });
-            const stored = yield* Effect.fromResult(
-              Schema.decodeUnknownResult(StoredShellSnapshot)(parsed),
-            ).pipe(Effect.mapError((cause) => shellPersistenceError("load-shell", cause)));
+            const stored = yield* decodeStoredShellSnapshot(parsed).pipe(
+              Effect.mapError(
+                (cause) =>
+                  new ConnectionPersistenceError({
+                    operation: "load-shell",
+                    stage: "decode",
+                    resource: "shell-cache",
+                    environmentId,
+                    cause,
+                  }),
+              ),
+            );
             return stored.environmentId === environmentId
               ? Option.some(stored.snapshot)
               : Option.none();
@@ -303,15 +377,38 @@ export const connectionStorageLayer = Layer.effectContext(
           }
           const legacyRaw = yield* Effect.tryPromise({
             try: () => legacyFile.text(),
-            catch: (cause) => shellPersistenceError("load-shell", cause),
+            catch: (cause) =>
+              new ConnectionPersistenceError({
+                operation: "load-shell",
+                stage: "read",
+                resource: "legacy-shell-cache",
+                environmentId,
+                cause,
+              }),
           });
           const legacyParsed = yield* Effect.try({
             try: () => JSON.parse(legacyRaw) as unknown,
-            catch: (cause) => shellPersistenceError("load-shell", cause),
+            catch: (cause) =>
+              new ConnectionPersistenceError({
+                operation: "load-shell",
+                stage: "parse",
+                resource: "legacy-shell-cache",
+                environmentId,
+                cause,
+              }),
           });
-          const legacyStored = yield* Effect.fromResult(
-            Schema.decodeUnknownResult(LegacyStoredShellSnapshot)(legacyParsed),
-          ).pipe(Effect.mapError((cause) => shellPersistenceError("load-shell", cause)));
+          const legacyStored = yield* decodeLegacyStoredShellSnapshot(legacyParsed).pipe(
+            Effect.mapError(
+              (cause) =>
+                new ConnectionPersistenceError({
+                  operation: "load-shell",
+                  stage: "decode",
+                  resource: "legacy-shell-cache",
+                  environmentId,
+                  cause,
+                }),
+            ),
+          );
           return legacyStored.environmentId === environmentId
             ? Option.some(legacyStored.snapshot)
             : Option.none();
@@ -324,9 +421,18 @@ export const connectionStorageLayer = Layer.effectContext(
             environmentId,
             snapshot,
           } as const;
-          const encoded = yield* Effect.fromResult(
-            Schema.encodeUnknownResult(StoredShellSnapshot)(stored),
-          ).pipe(Effect.mapError((cause) => shellPersistenceError("save-shell", cause)));
+          const encoded = yield* encodeStoredShellSnapshot(stored).pipe(
+            Effect.mapError(
+              (cause) =>
+                new ConnectionPersistenceError({
+                  operation: "save-shell",
+                  stage: "encode",
+                  resource: "shell-cache",
+                  environmentId,
+                  cause,
+                }),
+            ),
+          );
           yield* Effect.try({
             try: () => {
               if (!file.exists) {
@@ -334,7 +440,14 @@ export const connectionStorageLayer = Layer.effectContext(
               }
               file.write(JSON.stringify(encoded));
             },
-            catch: (cause) => shellPersistenceError("save-shell", cause),
+            catch: (cause) =>
+              new ConnectionPersistenceError({
+                operation: "save-shell",
+                stage: "write",
+                resource: "shell-cache",
+                environmentId,
+                cause,
+              }),
           });
         }),
       loadThread: (environmentId, threadId) =>
@@ -345,15 +458,41 @@ export const connectionStorageLayer = Layer.effectContext(
           }
           const raw = yield* Effect.tryPromise({
             try: () => file.text(),
-            catch: (cause) => shellPersistenceError("load-thread", cause),
+            catch: (cause) =>
+              new ConnectionPersistenceError({
+                operation: "load-thread",
+                stage: "read",
+                resource: "thread-cache",
+                environmentId,
+                threadId,
+                cause,
+              }),
           });
           const parsed = yield* Effect.try({
             try: () => JSON.parse(raw) as unknown,
-            catch: (cause) => shellPersistenceError("load-thread", cause),
+            catch: (cause) =>
+              new ConnectionPersistenceError({
+                operation: "load-thread",
+                stage: "parse",
+                resource: "thread-cache",
+                environmentId,
+                threadId,
+                cause,
+              }),
           });
-          const stored = yield* Effect.fromResult(
-            Schema.decodeUnknownResult(StoredThreadSnapshot)(parsed),
-          ).pipe(Effect.mapError((cause) => shellPersistenceError("load-thread", cause)));
+          const stored = yield* decodeStoredThreadSnapshot(parsed).pipe(
+            Effect.mapError(
+              (cause) =>
+                new ConnectionPersistenceError({
+                  operation: "load-thread",
+                  stage: "decode",
+                  resource: "thread-cache",
+                  environmentId,
+                  threadId,
+                  cause,
+                }),
+            ),
+          );
           return stored.environmentId === environmentId && stored.threadId === threadId
             ? Option.some(stored.thread)
             : Option.none();
@@ -361,14 +500,24 @@ export const connectionStorageLayer = Layer.effectContext(
       saveThread: (environmentId, thread) =>
         Effect.gen(function* () {
           const file = yield* threadSnapshotFile(environmentId, thread.id, "save-thread");
-          const encoded = yield* Effect.fromResult(
-            Schema.encodeUnknownResult(StoredThreadSnapshot)({
-              schemaVersion: THREAD_SNAPSHOT_CACHE_SCHEMA_VERSION,
-              environmentId,
-              threadId: thread.id,
-              thread,
-            }),
-          ).pipe(Effect.mapError((cause) => shellPersistenceError("save-thread", cause)));
+          const encoded = yield* encodeStoredThreadSnapshot({
+            schemaVersion: THREAD_SNAPSHOT_CACHE_SCHEMA_VERSION,
+            environmentId,
+            threadId: thread.id,
+            thread,
+          }).pipe(
+            Effect.mapError(
+              (cause) =>
+                new ConnectionPersistenceError({
+                  operation: "save-thread",
+                  stage: "encode",
+                  resource: "thread-cache",
+                  environmentId,
+                  threadId: thread.id,
+                  cause,
+                }),
+            ),
+          );
           yield* Effect.try({
             try: () => {
               if (!file.exists) {
@@ -376,36 +525,63 @@ export const connectionStorageLayer = Layer.effectContext(
               }
               file.write(JSON.stringify(encoded));
             },
-            catch: (cause) => shellPersistenceError("save-thread", cause),
+            catch: (cause) =>
+              new ConnectionPersistenceError({
+                operation: "save-thread",
+                stage: "write",
+                resource: "thread-cache",
+                environmentId,
+                threadId: thread.id,
+                cause,
+              }),
           });
         }),
       removeThread: (environmentId, threadId) =>
         Effect.gen(function* () {
           const file = yield* threadSnapshotFile(environmentId, threadId, "remove-thread");
           if (file.exists) {
-            file.delete();
+            yield* Effect.try({
+              try: () => file.delete(),
+              catch: (cause) =>
+                new ConnectionPersistenceError({
+                  operation: "remove-thread",
+                  stage: "remove",
+                  resource: "thread-cache",
+                  environmentId,
+                  threadId,
+                  cause,
+                }),
+            });
           }
-        }).pipe(
-          Effect.mapError((cause) =>
-            cause._tag === "ConnectionPersistenceError"
-              ? cause
-              : shellPersistenceError("remove-thread", cause),
-          ),
-        ),
+        }),
       clear: (environmentId) =>
         Effect.gen(function* () {
           const file = yield* shellSnapshotFile(environmentId, "clear-environment");
           if (file.exists) {
             yield* Effect.try({
               try: () => file.delete(),
-              catch: (cause) => shellPersistenceError("clear-environment", cause),
+              catch: (cause) =>
+                new ConnectionPersistenceError({
+                  operation: "clear-environment",
+                  stage: "remove",
+                  resource: "shell-cache",
+                  environmentId,
+                  cause,
+                }),
             });
           }
           const legacyFile = yield* legacyShellSnapshotFile(environmentId, "clear-environment");
           if (legacyFile.exists) {
             yield* Effect.try({
               try: () => legacyFile.delete(),
-              catch: (cause) => shellPersistenceError("clear-environment", cause),
+              catch: (cause) =>
+                new ConnectionPersistenceError({
+                  operation: "clear-environment",
+                  stage: "remove",
+                  resource: "legacy-shell-cache",
+                  environmentId,
+                  cause,
+                }),
             });
           }
           const threadDirectory = yield* threadSnapshotDirectory(
@@ -415,7 +591,14 @@ export const connectionStorageLayer = Layer.effectContext(
           if (threadDirectory.exists) {
             yield* Effect.try({
               try: () => threadDirectory.delete(),
-              catch: (cause) => shellPersistenceError("clear-environment", cause),
+              catch: (cause) =>
+                new ConnectionPersistenceError({
+                  operation: "clear-environment",
+                  stage: "remove",
+                  resource: "thread-cache",
+                  environmentId,
+                  cause,
+                }),
             });
           }
         }),
diff --git a/apps/mobile/src/features/cloud/dpop.test.ts b/apps/mobile/src/features/cloud/dpop.test.ts
index 8945d148ee9..608275ae8fc 100644
--- a/apps/mobile/src/features/cloud/dpop.test.ts
+++ b/apps/mobile/src/features/cloud/dpop.test.ts
@@ -9,8 +9,11 @@ import * as Effect from "effect/Effect";
 import { verifyDpopProof } from "@t3tools/shared/dpop";
 
 import {
+  CloudDpopProofError,
+  CloudDpopStorageError,
   createDpopProof,
   generateDpopProofKeyPair,
+  isCloudDpopError,
   loadOrCreateDpopProofKeyPair,
   cryptoLayer,
 } from "./dpop";
@@ -95,7 +98,82 @@ describe("mobile DPoP", () => {
 
       const error = yield* loadOrCreateDpopProofKeyPair().pipe(Effect.flip);
 
-      expect(error.message).toBe("Stored DPoP proof key is invalid.");
+      expect(error).toBeInstanceOf(CloudDpopStorageError);
+      expect(error).toMatchObject({
+        operation: "decode",
+        storageKey: "t3code.cloud.dpop-proof-key",
+      });
+      expect(isCloudDpopError(error)).toBe(true);
+    }).pipe(Effect.provide(cryptoLayer)),
+  );
+
+  it.effect("rejects stored key material whose public coordinates do not match", () =>
+    Effect.gen(function* () {
+      secureStore.clear();
+      const generated = yield* generateDpopProofKeyPair();
+      secureStore.set(
+        "t3code.cloud.dpop-proof-key",
+        JSON.stringify({ ...generated.privateJwk, x: generated.privateJwk.y }),
+      );
+
+      const error = yield* loadOrCreateDpopProofKeyPair().pipe(Effect.flip);
+
+      expect(error).toBeInstanceOf(CloudDpopStorageError);
+      expect(error).toMatchObject({
+        operation: "restore",
+        storageKey: "t3code.cloud.dpop-proof-key",
+      });
+    }).pipe(Effect.provide(cryptoLayer)),
+  );
+
+  it.effect("preserves request context for an invalid proof URL", () =>
+    Effect.gen(function* () {
+      const proofKey = yield* generateDpopProofKeyPair();
+      const error = yield* createDpopProof({
+        method: "POST",
+        url: "http://",
+        proofKey,
+      }).pipe(Effect.flip);
+
+      expect(error).toBeInstanceOf(CloudDpopProofError);
+      expect(error).toMatchObject({
+        operation: "normalize-url",
+        method: "POST",
+        requestTarget: "<invalid-url>",
+        urlLength: "http://".length,
+        thumbprint: proofKey.thumbprint,
+      });
+      expect(isCloudDpopError(error)).toBe(true);
+    }).pipe(Effect.provide(cryptoLayer)),
+  );
+
+  it.effect("redacts credentials and non-HTU URL components from proof failures", () =>
+    Effect.gen(function* () {
+      const proofKey = yield* generateDpopProofKeyPair();
+      const url = "https://user:password@example.com/oauth/token?access_token=secret#fragment";
+      const error = yield* createDpopProof({
+        method: "POST",
+        url,
+        proofKey: {
+          ...proofKey,
+          privateJwk: { ...proofKey.privateJwk, d: "%" },
+        },
+      }).pipe(Effect.flip);
+
+      expect(error).toBeInstanceOf(CloudDpopProofError);
+      expect(error).toMatchObject({
+        operation: "import-private-key",
+        method: "POST",
+        requestTarget: "https://example.com/oauth/token",
+        urlLength: url.length,
+        thumbprint: proofKey.thumbprint,
+      });
+      expect(error).not.toHaveProperty("url");
+      expect(error.message).not.toContain("user");
+      expect(error.message).not.toContain("password");
+      expect(error.message).not.toContain("access_token");
+      expect(error.message).not.toContain("secret");
+      expect(error.message).not.toContain("fragment");
     }).pipe(Effect.provide(cryptoLayer)),
   );
 
diff --git a/apps/mobile/src/features/cloud/dpop.ts b/apps/mobile/src/features/cloud/dpop.ts
index 0bd4b7ff1bd..3590ace8073 100644
--- a/apps/mobile/src/features/cloud/dpop.ts
+++ b/apps/mobile/src/features/cloud/dpop.ts
@@ -1,8 +1,8 @@
 import * as Clock from "effect/Clock";
 import * as Crypto from "effect/Crypto";
-import * as Data from "effect/Data";
 import * as Effect from "effect/Effect";
 import * as Encoding from "effect/Encoding";
+import * as Layer from "effect/Layer";
 import * as Result from "effect/Result";
 import * as Schema from "effect/Schema";
 import * as ExpoCrypto from "expo-crypto";
@@ -12,19 +12,91 @@ import {
   computeDpopAccessTokenHash,
   computeDpopJwkThumbprint,
   DpopPublicJwk,
-  normalizeDpopHtu,
+  redactDpopRequestTarget,
 } from "@t3tools/shared/dpop";
-import * as Layer from "effect/Layer";
 
-export class CloudDpopError extends Data.TaggedError("CloudDpopError")<{
-  readonly message: string;
-  readonly cause?: unknown;
-}> {}
+export class CloudDpopStorageError extends Schema.TaggedErrorClass<CloudDpopStorageError>()(
+  "CloudDpopStorageError",
+  {
+    operation: Schema.Literals(["read", "decode", "restore", "encode", "write"]),
+    storageKey: Schema.String,
+    cause: Schema.Defect(),
+  },
+) {
+  override get message(): string {
+    return `Mobile DPoP key storage operation "${this.operation}" failed for key "${this.storageKey}".`;
+  }
+}
+
+export class CloudDpopKeyError extends Schema.TaggedErrorClass<CloudDpopKeyError>()(
+  "CloudDpopKeyError",
+  {
+    operation: Schema.Literals(["generate-randomness", "derive-public-key"]),
+    cause: Schema.Defect(),
+  },
+) {
+  override get message(): string {
+    return `Mobile DPoP key operation "${this.operation}" failed.`;
+  }
+}
+
+export class CloudDpopProofError extends Schema.TaggedErrorClass<CloudDpopProofError>()(
+  "CloudDpopProofError",
+  {
+    operation: Schema.Literals([
+      "import-private-key",
+      "generate-id",
+      "normalize-url",
+      "encode-header",
+      "encode-payload",
+      "hash-signing-input",
+      "sign",
+    ]),
+    method: Schema.String,
+    requestTarget: Schema.String,
+    urlLength: Schema.Number,
+    thumbprint: Schema.String,
+    cause: Schema.Defect(),
+  },
+) {
+  override get message(): string {
+    return `Mobile DPoP proof operation "${this.operation}" failed for ${this.method.toUpperCase()} ${this.requestTarget}.`;
+  }
+}
 
-function cloudDpopError(message: string) {
-  return (cause: unknown) => new CloudDpopError({ message, cause });
+export class DpopPublicKeyFormatError extends Schema.TaggedErrorClass<DpopPublicKeyFormatError>()(
+  "DpopPublicKeyFormatError",
+  {
+    byteLength: Schema.Number,
+    firstByte: Schema.optional(Schema.Number),
+  },
+) {
+  override get message(): string {
+    const prefix =
+      this.firstByte === undefined
+        ? "no prefix byte"
+        : `prefix 0x${this.firstByte.toString(16).padStart(2, "0")}`;
+    return `Expected a 65-byte uncompressed P-256 public key beginning with 0x04; received ${this.byteLength} bytes with ${prefix}.`;
+  }
 }
 
+export class DpopStoredPublicKeyMismatchError extends Schema.TaggedErrorClass<DpopStoredPublicKeyMismatchError>()(
+  "DpopStoredPublicKeyMismatchError",
+  {},
+) {
+  override get message(): string {
+    return "Stored DPoP private and public key material do not match.";
+  }
+}
+
+export const CloudDpopError = Schema.Union([
+  CloudDpopStorageError,
+  CloudDpopKeyError,
+  CloudDpopProofError,
+]);
+export type CloudDpopError = typeof CloudDpopError.Type;
+export const isCloudDpopError = Schema.is(CloudDpopError);
+
 const DpopPrivateJwkSchema = Schema.Struct({
   ...DpopPublicJwk.fields,
   d: Schema.String,
@@ -97,29 +169,12 @@ function base64UrlToBytes(value: string): Uint8Array {
   return Result.getOrThrow(Encoding.decodeBase64Url(value));
 }
 
-function sha256Digest(
-  data: Uint8Array,
-  message: string,
-): Effect.Effect<Uint8Array, CloudDpopError, Crypto.Crypto> {
-  return Crypto.Crypto.pipe(
-    Effect.flatMap((crypto) => crypto.digest("SHA-256", data)),
-    Effect.mapError(cloudDpopError(message)),
-  );
-}
-
-function secureRandomBytes(
-  byteCount: number,
-  message: string,
-): Effect.Effect<Uint8Array, CloudDpopError, Crypto.Crypto> {
-  return Crypto.Crypto.pipe(
-    Effect.flatMap((crypto) => crypto.randomBytes(byteCount)),
-    Effect.mapError(cloudDpopError(message)),
-  );
-}
-
 function publicJwkFromUncompressedPublicKey(publicKey: Uint8Array): DpopPublicJwk {
   if (publicKey.length !== 65 || publicKey[0] !== 0x04) {
-    throw new Error("Generated DPoP public key is not an uncompressed P-256 point.");
+    throw new DpopPublicKeyFormatError({
+      byteLength: publicKey.length,
+      ...(publicKey[0] === undefined ? {} : { firstByte: publicKey[0] }),
+    });
   }
   return {
     kty: "EC",
@@ -144,14 +199,16 @@ export function generateDpopProofKeyPair(): Effect.Effect<
   return Effect.gen(function* () {
     let privateKey: Uint8Array;
     do {
-      privateKey = yield* secureRandomBytes(
-        p256.CURVE.nByteLength,
-        "Could not generate DPoP key pair randomness.",
+      privateKey = yield* Crypto.Crypto.pipe(
+        Effect.flatMap((crypto) => crypto.randomBytes(p256.CURVE.nByteLength)),
+        Effect.mapError(
+          (cause) => new CloudDpopKeyError({ operation: "generate-randomness", cause }),
+        ),
       );
     } while (!p256.utils.isValidPrivateKey(privateKey));
     const publicJwk = yield* Effect.try({
       try: () => publicJwkFromUncompressedPublicKey(p256.getPublicKey(privateKey, false)),
-      catch: cloudDpopError("Generated DPoP public key is invalid."),
+      catch: (cause) => new CloudDpopKeyError({ operation: "derive-public-key", cause }),
     });
     const thumbprint = computeDpopJwkThumbprint(publicJwk);
     return {
@@ -170,11 +227,23 @@ export function loadOrCreateDpopProofKeyPair(): Effect.Effect<
   return Effect.gen(function* () {
     const stored = yield* Effect.tryPromise({
       try: () => SecureStore.getItemAsync(DPOP_PROOF_KEY_STORAGE_KEY),
-      catch: cloudDpopError("Could not read the DPoP proof key."),
+      catch: (cause) =>
+        new CloudDpopStorageError({
+          operation: "read",
+          storageKey: DPOP_PROOF_KEY_STORAGE_KEY,
+          cause,
+        }),
     });
     if (stored) {
       const storedPrivateJwk = yield* decodeDpopPrivateJwkJson(stored).pipe(
-        Effect.mapError(cloudDpopError("Stored DPoP proof key is invalid.")),
+        Effect.mapError(
+          (cause) =>
+            new CloudDpopStorageError({
+              operation: "decode",
+              storageKey: DPOP_PROOF_KEY_STORAGE_KEY,
+              cause,
+            }),
+        ),
       );
       const restored = yield* Effect.try({
         try: () => {
@@ -183,11 +252,16 @@ export function loadOrCreateDpopProofKeyPair(): Effect.Effect<
             p256.getPublicKey(privateKey, false),
           );
           if (publicJwk.x !== storedPrivateJwk.x || publicJwk.y !== storedPrivateJwk.y) {
-            throw new Error("Stored DPoP key does not match its public key.");
+            throw new DpopStoredPublicKeyMismatchError();
           }
           return { privateJwk: storedPrivateJwk, publicJwk };
         },
-        catch: cloudDpopError("Stored DPoP proof key is invalid."),
+        catch: (cause) =>
+          new CloudDpopStorageError({
+            operation: "restore",
+            storageKey: DPOP_PROOF_KEY_STORAGE_KEY,
+            cause,
+          }),
       });
       return {
         ...restored,
@@ -196,23 +270,28 @@ export function loadOrCreateDpopProofKeyPair(): Effect.Effect<
     }
     const generated = yield* generateDpopProofKeyPair();
     const encodedPrivateJwk = yield* encodeDpopPrivateJwkJson(generated.privateJwk).pipe(
-      Effect.mapError(cloudDpopError("Could not encode the DPoP proof key.")),
+      Effect.mapError(
+        (cause) =>
+          new CloudDpopStorageError({
+            operation: "encode",
+            storageKey: DPOP_PROOF_KEY_STORAGE_KEY,
+            cause,
+          }),
+      ),
     );
     yield* Effect.tryPromise({
       try: () => SecureStore.setItemAsync(DPOP_PROOF_KEY_STORAGE_KEY, encodedPrivateJwk),
-      catch: cloudDpopError("Could not store the DPoP proof key."),
+      catch: (cause) =>
+        new CloudDpopStorageError({
+          operation: "write",
+          storageKey: DPOP_PROOF_KEY_STORAGE_KEY,
+          cause,
+        }),
     });
     return generated;
   });
 }
 
-function normalizeHtu(url: string): Effect.Effect<string, CloudDpopError> {
-  const normalized = normalizeDpopHtu(url);
-  return normalized
-    ? Effect.succeed(normalized)
-    : Effect.fail(new CloudDpopError({ message: "DPoP URL is invalid." }));
-}
-
 export function createDpopProof(input: {
   readonly method: string;
   readonly url: string;
@@ -225,23 +304,69 @@ export function createDpopProof(input: {
 > {
   return Effect.gen(function* () {
     const keyPair = input.proofKey ?? (yield* generateDpopProofKeyPair());
+    const requestTarget = redactDpopRequestTarget(input.url);
+    const urlLength = input.url.length;
     const privateKey = yield* Effect.try({
       try: () => base64UrlToBytes(keyPair.privateJwk.d),
-      catch: cloudDpopError("Could not import DPoP private key."),
+      catch: (cause) =>
+        new CloudDpopProofError({
+          operation: "import-private-key",
+          method: input.method,
+          requestTarget,
+          urlLength,
+          thumbprint: keyPair.thumbprint,
+          cause,
+        }),
     });
     const nowMs = yield* Clock.currentTimeMillis;
     const jti = yield* Crypto.Crypto.pipe(
       Effect.flatMap((crypto) => crypto.randomUUIDv4),
-      Effect.mapError(cloudDpopError("Could not generate DPoP proof identifier.")),
+      Effect.mapError(
+        (cause) =>
+          new CloudDpopProofError({
+            operation: "generate-id",
+            method: input.method,
+            requestTarget,
+            urlLength,
+            thumbprint: keyPair.thumbprint,
+            cause,
+          }),
+      ),
     );
-    const htu = yield* normalizeHtu(input.url);
+    const htu = yield* Effect.try({
+      try: () => {
+        const parsed = new URL(input.url);
+        parsed.hash = "";
+        parsed.search = "";
+        return parsed.toString();
+      },
+      catch: (cause) =>
+        new CloudDpopProofError({
+          operation: "normalize-url",
+          method: input.method,
+          requestTarget,
+          urlLength,
+          thumbprint: keyPair.thumbprint,
+          cause,
+        }),
+    });
     const header = yield* encodeDpopJwtHeaderJson({
       typ: "dpop+jwt",
       alg: "ES256",
       jwk: keyPair.publicJwk,
     }).pipe(
       Effect.map(Encoding.encodeBase64Url),
-      Effect.mapError(cloudDpopError("Could not encode DPoP proof header.")),
+      Effect.mapError(
+        (cause) =>
+          new CloudDpopProofError({
+            operation: "encode-header",
+            method: input.method,
+            requestTarget,
+            urlLength,
+            thumbprint: keyPair.thumbprint,
+            cause,
+          }),
+      ),
     );
     const ath = input.accessToken ? computeDpopAccessTokenHash(input.accessToken) : null;
     const payload = yield* encodeDpopJwtPayloadJson({
@@ -252,15 +377,45 @@ export function createDpopProof(input: {
       ...(ath ? { ath } : {}),
     }).pipe(
       Effect.map(Encoding.encodeBase64Url),
-      Effect.mapError(cloudDpopError("Could not encode DPoP proof payload.")),
+      Effect.mapError(
+        (cause) =>
+          new CloudDpopProofError({
+            operation: "encode-payload",
+            method: input.method,
+            requestTarget,
+            urlLength,
+            thumbprint: keyPair.thumbprint,
+            cause,
+          }),
+      ),
     );
-    const signatureInputHash = yield* sha256Digest(
-      new TextEncoder().encode(`${header}.${payload}`),
-      "Could not hash DPoP signing input.",
+    const signatureInputHash = yield* Crypto.Crypto.pipe(
+      Effect.flatMap((crypto) =>
+        crypto.digest("SHA-256", new TextEncoder().encode(`${header}.${payload}`)),
+      ),
+      Effect.mapError(
+        (cause) =>
+          new CloudDpopProofError({
+            operation: "hash-signing-input",
+            method: input.method,
+            requestTarget,
+            urlLength,
+            thumbprint: keyPair.thumbprint,
+            cause,
+          }),
+      ),
     );
     const signature = yield* Effect.try({
       try: () => p256.sign(signatureInputHash, privateKey, { prehash: false }).toCompactRawBytes(),
-      catch: cloudDpopError("Could not sign DPoP proof."),
+      catch: (cause) =>
+        new CloudDpopProofError({
+          operation: "sign",
+          method: input.method,
+          requestTarget,
+          urlLength,
+          thumbprint: keyPair.thumbprint,
+          cause,
+        }),
     });
     return {
       proof: `${header}.${payload}.${Encoding.encodeBase64Url(signature)}`,
diff --git a/apps/mobile/src/features/cloud/linkEnvironment.test.ts b/apps/mobile/src/features/cloud/linkEnvironment.test.ts
index b9ab3aeab05..59c6355b9a0 100644
--- a/apps/mobile/src/features/cloud/linkEnvironment.test.ts
+++ b/apps/mobile/src/features/cloud/linkEnvironment.test.ts
@@ -9,9 +9,11 @@ import { remoteHttpClientLayer } from "@t3tools/client-runtime/rpc";
 import { HttpClient } from "effect/unstable/http";
 
 import {
+  CloudEnvironmentLinkOperationError,
   cloudEnvironmentsPendingStatus,
   linkEnvironmentToCloud,
   connectCloudEnvironment,
+  isCloudEnvironmentLinkError,
   listCloudEnvironments,
   listCloudEnvironmentsWithStatus,
   normalizeRelayBaseUrl,
@@ -148,6 +150,46 @@ describe("mobile cloud link environment client", () => {
     createProofMock.mockClear();
   });
 
+  it("keeps URL secrets out of operation error diagnostics", () => {
+    const relayUrl =
+      "https://relay-user:relay-password@relay.example.test/private/workspace?access_token=relay-secret#relay-fragment";
+    const httpBaseUrl =
+      "https://desktop-user:desktop-password@desktop.example.test/private/workspace?access_token=desktop-secret#desktop-fragment";
+    const cause = new Error("request failed");
+
+    const error = CloudEnvironmentLinkOperationError.fromCause({
+      action: "link the environment",
+      cause,
+      environmentId: "env-1",
+      relayUrl,
+      httpBaseUrl,
+    });
+
+    expect(error).toMatchObject({
+      relayUrlInputLength: relayUrl.length,
+      relayUrlProtocol: "https:",
+      relayUrlHostname: "relay.example.test",
+      httpBaseUrlInputLength: httpBaseUrl.length,
+      httpBaseUrlProtocol: "https:",
+      httpBaseUrlHostname: "desktop.example.test",
+    });
+    const serialized = JSON.stringify(error);
+    for (const secret of [
+      "relay-user",
+      "relay-password",
+      "relay-secret",
+      "relay-fragment",
+      "/private/workspace",
+      "desktop-user",
+      "desktop-password",
+      "desktop-secret",
+      "desktop-fragment",
+    ]) {
+      expect(serialized).not.toContain(secret);
+      expect(error.message).not.toContain(secret);
+    }
+  });
+
   it("normalizes configured relay base URLs before building DPoP-bound requests", () => {
     expect(normalizeRelayBaseUrl(" https://relay.example.test/// ")).toBe(
       "https://relay.example.test",
@@ -235,9 +277,14 @@ describe("mobile cloud link environment client", () => {
         listCloudEnvironments({ clerkToken: "clerk-token" }),
       ).pipe(Effect.flip);
       expect(error).toMatchObject({
-        _tag: "CloudEnvironmentLinkError",
-        message: "https://relay.example.test/v1/environments failed",
+        _tag: "CloudEnvironmentLinkOperationError",
+        action: "list cloud environments",
+        relayUrlInputLength: "https://relay.example.test".length,
+        relayUrlProtocol: "https:",
+        relayUrlHostname: "relay.example.test",
       });
+      expect(error.message).toBe("Could not list cloud environments.");
+      expect(isCloudEnvironmentLinkError(error)).toBe(true);
     }),
   );
 
@@ -498,7 +545,7 @@ describe("mobile cloud link environment client", () => {
             label: "Desktop",
           },
           status: null,
-          statusError: "https://relay.example.test/v1/environments/env-1/status failed",
+          statusError: 'Could not read cloud environment status for environment "env-1".',
         },
       ]);
     }),
@@ -562,7 +609,8 @@ describe("mobile cloud link environment client", () => {
             label: "Desktop",
           },
           status: null,
-          statusError: "Relay returned status for a different environment.",
+          statusError:
+            'The environment status response identified environment "env-other" instead of "env-1".',
         },
       ]);
     }),
@@ -590,13 +638,55 @@ describe("mobile cloud link environment client", () => {
           }),
         ).pipe(Effect.flip);
         expect(error).toMatchObject({
-          _tag: "CloudEnvironmentLinkError",
-          message: "Relay returned credentials for a different environment.",
+          _tag: "CloudEnvironmentIdMismatchError",
+          source: "environment link response",
+          expectedEnvironmentId: "env-1",
+          actualEnvironmentId: "env-other",
         });
         expect(fetchMock).toHaveBeenCalledTimes(3);
       }),
   );
 
+  it.effect("reports invalid endpoint URLs with redacted diagnostics", () =>
+    Effect.gen(function* () {
+      vi.stubGlobal(
+        "fetch",
+        vi.fn(() => Promise.resolve(Response.json(validLinkChallengeResponse()))),
+      );
+
+      const httpBaseUrl =
+        "https://desktop-user:desktop-password@[invalid-host]/private/workspace?access_token=desktop-secret#desktop-fragment";
+      const error = yield* withCloudServices(
+        linkEnvironmentToCloud({
+          clerkToken: "clerk-token",
+          connection: {
+            ...savedConnection,
+            httpBaseUrl,
+          },
+        }),
+      ).pipe(Effect.flip);
+
+      expect(error).toMatchObject({
+        _tag: "CloudEnvironmentLinkOperationError",
+        action: "derive the environment endpoint origin",
+        environmentId: "env-1",
+        httpBaseUrlInputLength: httpBaseUrl.length,
+      });
+      expect(error).not.toHaveProperty("httpBaseUrl");
+      const serialized = JSON.stringify({ ...error, cause: undefined });
+      for (const secret of [
+        "desktop-user",
+        "desktop-password",
+        "/private/workspace",
+        "desktop-secret",
+        "desktop-fragment",
+      ]) {
+        expect(serialized).not.toContain(secret);
+        expect(error.message).not.toContain(secret);
+      }
+    }),
+  );
+
   it.effect("preserves typed local environment failures while obtaining a link proof", () =>
     Effect.gen(function* () {
       const fetchMock = vi.fn((url: string | URL) => {
@@ -607,7 +697,8 @@ describe("mobile cloud link environment client", () => {
           Response.json(
             {
               _tag: "EnvironmentHttpUnauthorizedError",
-              message: "Invalid environment bearer session.",
+              reason: "cloud_cli_authorization_required",
+              message: "Run `t3 connect link` to authorize this environment.",
             },
             { status: 401 },
           ),
@@ -621,9 +712,20 @@ describe("mobile cloud link environment client", () => {
           connection: savedConnection,
         }),
       ).pipe(Effect.flip);
-      expect(error._tag).toBe("CloudEnvironmentLinkError");
+      expect(error).toMatchObject({
+        _tag: "CloudEnvironmentLinkOperationError",
+        action: "obtain an environment link proof",
+        environmentId: "env-1",
+        httpBaseUrlInputLength: "https://desktop.example.test/".length,
+        httpBaseUrlProtocol: "https:",
+        httpBaseUrlHostname: "desktop.example.test",
+        environmentError: {
+          _tag: "EnvironmentHttpUnauthorizedError",
+          reason: "cloud_cli_authorization_required",
+        },
+      });
       expect(error.message).toBe(
-        "Could not obtain environment link proof: Invalid environment bearer session.",
+        'Could not obtain an environment link proof for environment "env-1".',
       );
       expect(fetchMock).toHaveBeenCalledTimes(2);
     }),
@@ -659,11 +761,19 @@ describe("mobile cloud link environment client", () => {
         }),
       ).pipe(Effect.flip);
       expect(error).toMatchObject({
-        _tag: "CloudEnvironmentLinkError",
-        message:
-          "https://relay.example.test/v1/client/environment-links failed: Relay rejected the environment link proof (origin_not_allowed).",
+        _tag: "CloudEnvironmentLinkOperationError",
+        action: "link the environment",
+        environmentId: "env-1",
+        relayUrlInputLength: "https://relay.example.test".length,
+        relayUrlProtocol: "https:",
+        relayUrlHostname: "relay.example.test",
         traceId: "trace-test",
+        relayError: {
+          _tag: "RelayEnvironmentLinkProofInvalidError",
+          reason: "origin_not_allowed",
+        },
       });
+      expect(error.message).toBe('Could not link the environment for environment "env-1".');
       expect(fetchMock).toHaveBeenCalledTimes(3);
     }),
   );
@@ -696,8 +806,10 @@ describe("mobile cloud link environment client", () => {
         }),
       ).pipe(Effect.flip);
       expect(error).toMatchObject({
-        _tag: "CloudEnvironmentLinkError",
-        message: "Relay returned credentials for a different endpoint provider.",
+        _tag: "CloudEnvironmentEndpointProviderMismatchError",
+        environmentId: "env-1",
+        expectedProviderKind: "cloudflare_tunnel",
+        actualProviderKind: "manual",
       });
       expect(fetchMock).toHaveBeenCalledTimes(3);
     }),
@@ -962,8 +1074,10 @@ describe("mobile cloud link environment client", () => {
         }),
       ).pipe(Effect.flip);
       expect(error).toMatchObject({
-        _tag: "CloudEnvironmentLinkError",
-        message: "Relay returned credentials for a different environment.",
+        _tag: "CloudEnvironmentIdMismatchError",
+        source: "environment connect response",
+        expectedEnvironmentId: "env-1",
+        actualEnvironmentId: "env-other",
       });
     }),
   );
@@ -1005,11 +1119,21 @@ describe("mobile cloud link environment client", () => {
         }),
       ).pipe(Effect.flip);
       expect(error).toMatchObject({
-        _tag: "CloudEnvironmentLinkError",
-        message:
-          "https://relay.example.test/v1/environments/env-1/connect failed: Relay rejected the DPoP proof.",
+        _tag: "CloudEnvironmentLinkOperationError",
+        action: "connect to the cloud environment",
+        environmentId: "env-1",
+        relayUrlInputLength: "https://relay.example.test".length,
+        relayUrlProtocol: "https:",
+        relayUrlHostname: "relay.example.test",
         traceId: "trace-connect",
+        relayError: {
+          _tag: "RelayAuthInvalidError",
+          reason: "invalid_dpop",
+        },
       });
+      expect(error.message).toBe(
+        'Could not connect to the cloud environment for environment "env-1".',
+      );
     }),
   );
 
@@ -1051,8 +1175,23 @@ describe("mobile cloud link environment client", () => {
         }),
       ).pipe(Effect.flip);
       expect(error).toMatchObject({
-        _tag: "CloudEnvironmentLinkError",
-        message: "Relay returned credentials for a different endpoint.",
+        _tag: "CloudEnvironmentEndpointMismatchError",
+        source: "environment connect response",
+        environmentId: "env-1",
+        expectedProviderKind: "cloudflare_tunnel",
+        expectedHttpBaseUrlInputLength: "https://desktop.example.test/".length,
+        expectedHttpBaseUrlProtocol: "https:",
+        expectedHttpBaseUrlHostname: "desktop.example.test",
+        expectedWsBaseUrlInputLength: "wss://desktop.example.test/ws".length,
+        expectedWsBaseUrlProtocol: "wss:",
+        expectedWsBaseUrlHostname: "desktop.example.test",
+        actualProviderKind: "cloudflare_tunnel",
+        actualHttpBaseUrlInputLength: "https://other-desktop.example.test/".length,
+        actualHttpBaseUrlProtocol: "https:",
+        actualHttpBaseUrlHostname: "other-desktop.example.test",
+        actualWsBaseUrlInputLength: "wss://other-desktop.example.test/ws".length,
+        actualWsBaseUrlProtocol: "wss:",
+        actualWsBaseUrlHostname: "other-desktop.example.test",
       });
     }),
   );
@@ -1105,8 +1244,10 @@ describe("mobile cloud link environment client", () => {
           }),
         ).pipe(Effect.flip);
         expect(error).toMatchObject({
-          _tag: "CloudEnvironmentLinkError",
-          message: "Connected endpoint descriptor does not match the selected environment.",
+          _tag: "CloudEnvironmentIdMismatchError",
+          source: "connected environment descriptor",
+          expectedEnvironmentId: "env-1",
+          actualEnvironmentId: "env-other",
         });
       }),
   );
diff --git a/apps/mobile/src/features/cloud/linkEnvironment.ts b/apps/mobile/src/features/cloud/linkEnvironment.ts
index a77ca628978..ea70eec6656 100644
--- a/apps/mobile/src/features/cloud/linkEnvironment.ts
+++ b/apps/mobile/src/features/cloud/linkEnvironment.ts
@@ -1,4 +1,3 @@
-import * as Data from "effect/Data";
 import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
 import { HttpClient } from "effect/unstable/http";
@@ -17,16 +16,17 @@ import {
   RelayEnvironmentConnectScope,
   RelayEnvironmentStatusScope,
   type RelayDpopAccessTokenScope,
-  type RelayProtectedError as RelayProtectedErrorType,
   type RelayClientEnvironmentRecord,
   type RelayEnvironmentStatusResponse as RelayEnvironmentStatusResponseType,
-  type RelayManagedEndpointProviderKind,
+  RelayManagedEndpointProviderKind,
+  RelayProtectedError,
 } from "@t3tools/contracts/relay";
 import { exchangeRemoteDpopAccessToken } from "@t3tools/client-runtime/authorization";
 import { fetchRemoteEnvironmentDescriptor } from "@t3tools/client-runtime/environment";
 import { findErrorTraceId } from "@t3tools/client-runtime/errors";
 import { ManagedRelay } from "@t3tools/client-runtime/relay";
 import { makeEnvironmentHttpApiClient } from "@t3tools/client-runtime/rpc";
+import { getUrlDiagnostics } from "@t3tools/shared/urlDiagnostics";
 
 import { authClientMetadata } from "../../lib/authClientMetadata";
 import type { SavedRemoteConnection } from "../../lib/connection";
@@ -50,144 +50,316 @@ function readRelayUrl(): string | null {
   return resolveCloudPublicConfig().relay.url;
 }
 
-export class CloudEnvironmentLinkError extends Data.TaggedError("CloudEnvironmentLinkError")<{
-  readonly message: string;
-  readonly cause?: unknown;
-  readonly traceId?: string;
-}> {}
+const EnvironmentCloudApiError = Schema.Union([
+  EnvironmentHttpBadRequestError,
+  EnvironmentHttpUnauthorizedError,
+  EnvironmentHttpForbiddenError,
+  EnvironmentHttpConflictError,
+  EnvironmentHttpInternalServerError,
+  EnvironmentCloudEndpointUnavailableError,
+]);
+type EnvironmentCloudApiError = typeof EnvironmentCloudApiError.Type;
+const isEnvironmentCloudApiError = Schema.is(EnvironmentCloudApiError);
+const isManagedRelayRequestFailedError = Schema.is(ManagedRelay.ManagedRelayRequestFailedError);
+
+export const CloudEnvironmentLinkAction = Schema.Literals([
+  "load the mobile device id",
+  "load mobile notification preferences",
+  "create an environment link challenge",
+  "obtain an environment link proof",
+  "link the environment",
+  "configure environment relay access",
+  "list cloud environments",
+  "read cloud environment status",
+  "connect to the cloud environment",
+  "fetch the connected environment descriptor",
+  "create a bootstrap DPoP proof",
+  "exchange a managed endpoint DPoP access token",
+  "derive the environment endpoint origin",
+  "initialize the environment HTTP client",
+  "parse the managed endpoint URL",
+]);
+export type CloudEnvironmentLinkAction = typeof CloudEnvironmentLinkAction.Type;
+
+function relayUrlDiagnosticFields(relayUrl: string | undefined) {
+  if (relayUrl === undefined) {
+    return {};
+  }
+  const diagnostics = getUrlDiagnostics(relayUrl);
+  return {
+    relayUrlInputLength: diagnostics.inputLength,
+    ...(diagnostics.protocol === undefined ? {} : { relayUrlProtocol: diagnostics.protocol }),
+    ...(diagnostics.hostname === undefined ? {} : { relayUrlHostname: diagnostics.hostname }),
+  };
+}
 
-export interface CloudEnvironmentRecordWithStatus {
-  readonly environment: RelayClientEnvironmentRecord;
-  readonly status: RelayEnvironmentStatusResponseType | null;
-  readonly statusError: string | null;
+function httpBaseUrlDiagnosticFields(httpBaseUrl: string | undefined) {
+  if (httpBaseUrl === undefined) {
+    return {};
+  }
+  const diagnostics = getUrlDiagnostics(httpBaseUrl);
+  return {
+    httpBaseUrlInputLength: diagnostics.inputLength,
+    ...(diagnostics.protocol === undefined ? {} : { httpBaseUrlProtocol: diagnostics.protocol }),
+    ...(diagnostics.hostname === undefined ? {} : { httpBaseUrlHostname: diagnostics.hostname }),
+  };
 }
 
-const isEnvironmentCloudApiError = Schema.is(
-  Schema.Union([
-    EnvironmentHttpBadRequestError,
-    EnvironmentHttpUnauthorizedError,
-    EnvironmentHttpForbiddenError,
-    EnvironmentHttpConflictError,
-    EnvironmentHttpInternalServerError,
-    EnvironmentCloudEndpointUnavailableError,
-  ]),
-);
+export class CloudEnvironmentLinkOperationError extends Schema.TaggedErrorClass<CloudEnvironmentLinkOperationError>()(
+  "CloudEnvironmentLinkOperationError",
+  {
+    action: CloudEnvironmentLinkAction,
+    environmentId: Schema.optionalKey(Schema.String),
+    relayUrlInputLength: Schema.optionalKey(Schema.Number),
+    relayUrlProtocol: Schema.optionalKey(Schema.String),
+    relayUrlHostname: Schema.optionalKey(Schema.String),
+    httpBaseUrlInputLength: Schema.optionalKey(Schema.Number),
+    httpBaseUrlProtocol: Schema.optionalKey(Schema.String),
+    httpBaseUrlHostname: Schema.optionalKey(Schema.String),
+    traceId: Schema.optionalKey(Schema.String),
+    relayError: Schema.optionalKey(RelayProtectedError),
+    environmentError: Schema.optionalKey(EnvironmentCloudApiError),
+    cause: Schema.Defect(),
+  },
+) {
+  static fromCause(input: {
+    readonly action: CloudEnvironmentLinkAction;
+    readonly cause: unknown;
+    readonly environmentId?: string;
+    readonly relayUrl?: string;
+    readonly httpBaseUrl?: string;
+  }): CloudEnvironmentLinkOperationError {
+    const relayFailure = isManagedRelayRequestFailedError(input.cause) ? input.cause : undefined;
+    const environmentError = CloudEnvironmentLinkOperationError.findEnvironmentApiError(
+      input.cause,
+    );
+    const traceId = relayFailure?.traceId ?? findErrorTraceId(input.cause);
+    return new CloudEnvironmentLinkOperationError({
+      action: input.action,
+      cause: input.cause,
+      ...(input.environmentId === undefined ? {} : { environmentId: input.environmentId }),
+      ...relayUrlDiagnosticFields(input.relayUrl),
+      ...httpBaseUrlDiagnosticFields(input.httpBaseUrl),
+      ...(traceId === null || traceId === undefined ? {} : { traceId }),
+      ...(relayFailure?.relayError === undefined ? {} : { relayError: relayFailure.relayError }),
+      ...(environmentError === undefined ? {} : { environmentError }),
+    });
+  }
 
-const MANAGED_ENDPOINT_PROVIDER_KIND =
-  "cloudflare_tunnel" satisfies RelayManagedEndpointProviderKind;
+  private static findEnvironmentApiError(cause: unknown): EnvironmentCloudApiError | undefined {
+    const seen = new Set<unknown>();
+    let current = cause;
+    while (typeof current === "object" && current !== null && !seen.has(current)) {
+      if (isEnvironmentCloudApiError(current)) {
+        return current;
+      }
+      seen.add(current);
+      current = "cause" in current ? current.cause : undefined;
+    }
+    return undefined;
+  }
 
-function cloudEnvironmentLinkError(message: string) {
-  return (cause: unknown) => {
-    const environmentError = findEnvironmentCloudApiError(cause);
-    const traceId = findErrorTraceId(cause);
-    return new CloudEnvironmentLinkError({
-      message: environmentError
-        ? `${message.replace(/[.:]$/, "")}: ${environmentError.message}`
-        : withDevCause(message, cause),
-      cause,
-      ...(traceId === null ? {} : { traceId }),
-    });
-  };
+  override get message(): string {
+    const environment =
+      this.environmentId === undefined ? "" : ` for environment "${this.environmentId}"`;
+    return `Could not ${this.action}${environment}.`;
+  }
 }
 
-function isDevRuntime(): boolean {
-  return typeof __DEV__ !== "undefined" && __DEV__;
+export class CloudRelayUrlNotConfiguredError extends Schema.TaggedErrorClass<CloudRelayUrlNotConfiguredError>()(
+  "CloudRelayUrlNotConfiguredError",
+  {},
+) {
+  override get message(): string {
+    return "Relay URL is not configured.";
+  }
 }
 
-function causeMessage(cause: unknown): string | null {
-  if (cause instanceof Error && cause.message) {
-    return cause.message;
-  }
-  if (typeof cause === "object" && cause !== null) {
-    const record = cause as { readonly message?: unknown; readonly cause?: unknown };
-    if (typeof record.message === "string" && record.message.length > 0) {
-      const nested = causeMessage(record.cause);
-      return nested ? `${record.message}: ${nested}` : record.message;
-    }
+export class CloudEnvironmentLocalBearerRequiredError extends Schema.TaggedErrorClass<CloudEnvironmentLocalBearerRequiredError>()(
+  "CloudEnvironmentLocalBearerRequiredError",
+  {
+    environmentId: Schema.String,
+    httpBaseUrlInputLength: Schema.Number,
+    httpBaseUrlProtocol: Schema.optionalKey(Schema.String),
+    httpBaseUrlHostname: Schema.optionalKey(Schema.String),
+  },
+) {
+  static fromConnection(input: {
+    readonly environmentId: string;
+    readonly httpBaseUrl: string;
+  }): CloudEnvironmentLocalBearerRequiredError {
+    const diagnostics = getUrlDiagnostics(input.httpBaseUrl);
+    return new CloudEnvironmentLocalBearerRequiredError({
+      environmentId: input.environmentId,
+      httpBaseUrlInputLength: diagnostics.inputLength,
+      ...(diagnostics.protocol === undefined ? {} : { httpBaseUrlProtocol: diagnostics.protocol }),
+      ...(diagnostics.hostname === undefined ? {} : { httpBaseUrlHostname: diagnostics.hostname }),
+    });
   }
-  return null;
-}
 
-function withDevCause(message: string, cause: unknown): string {
-  if (!isDevRuntime()) {
-    return message;
+  override get message(): string {
+    return "Only a locally paired bearer connection can be linked to the cloud.";
   }
-  const detail = causeMessage(cause);
-  return detail ? `${message} (${detail})` : message;
 }
 
-function relayProtectedErrorMessage(error: RelayProtectedErrorType): string {
-  switch (error._tag) {
-    case "RelayAuthInvalidError":
-      switch (error.reason) {
-        case "missing_bearer":
-        case "invalid_bearer":
-          return "Relay rejected the cloud session token.";
-        case "invalid_dpop":
-          return "Relay rejected the DPoP proof.";
-        case "not_authorized":
-          return "Relay rejected the authenticated request.";
-      }
-    case "RelayEnvironmentLinkProofExpiredError":
-      return "Relay rejected an expired environment link proof.";
-    case "RelayEnvironmentLinkProofInvalidError":
-      return `Relay rejected the environment link proof (${error.reason}).`;
-    case "RelayEnvironmentConnectNotAuthorizedError":
-      return "Relay rejected the environment connection request.";
-    case "RelayEnvironmentEndpointUnavailableError":
-      return `Relay could not reach the environment endpoint (${error.reason}).`;
-    case "RelayEnvironmentEndpointTimedOutError":
-      return "Relay timed out while contacting the environment endpoint.";
-    case "RelayEnvironmentLinkFailedError":
-      return `Relay could not link the environment (${error.reason}).`;
-    case "RelayEnvironmentLinkUnavailableError":
-      return `Relay cannot provision the managed endpoint (${error.reason}).`;
-    case "RelayAgentActivityPublishProofExpiredError":
-      return "Relay rejected an expired agent activity publish proof.";
-    case "RelayAgentActivityPublishProofInvalidError":
-      return `Relay rejected the agent activity publish proof (${error.reason}).`;
-    case "RelayInternalError":
-      return `Relay encountered an internal error (${error.reason}).`;
+export class CloudEnvironmentIdMismatchError extends Schema.TaggedErrorClass<CloudEnvironmentIdMismatchError>()(
+  "CloudEnvironmentIdMismatchError",
+  {
+    source: Schema.Literals([
+      "environment link response",
+      "environment status response",
+      "environment status descriptor",
+      "environment connect response",
+      "connected environment descriptor",
+    ]),
+    expectedEnvironmentId: Schema.String,
+    actualEnvironmentId: Schema.String,
+  },
+) {
+  override get message(): string {
+    return `The ${this.source} identified environment "${this.actualEnvironmentId}" instead of "${this.expectedEnvironmentId}".`;
   }
 }
 
-function decodedRelayClientError(message: string) {
-  return (cause: ManagedRelay.ManagedRelayClientError) => {
-    const relayError =
-      cause._tag === "ManagedRelayRequestFailedError" ? cause.relayError : undefined;
-    const traceId = cause._tag === "ManagedRelayRequestFailedError" ? cause.traceId : undefined;
-    const detail = relayError ? relayProtectedErrorMessage(relayError) : null;
-    return new CloudEnvironmentLinkError({
-      message: detail ? `${message}: ${detail}` : message,
-      cause,
-      ...(traceId ? { traceId } : {}),
+export class CloudEnvironmentEndpointMismatchError extends Schema.TaggedErrorClass<CloudEnvironmentEndpointMismatchError>()(
+  "CloudEnvironmentEndpointMismatchError",
+  {
+    source: Schema.Literals(["environment status response", "environment connect response"]),
+    environmentId: Schema.String,
+    expectedProviderKind: RelayManagedEndpointProviderKind,
+    expectedHttpBaseUrlInputLength: Schema.Number,
+    expectedHttpBaseUrlProtocol: Schema.optionalKey(Schema.String),
+    expectedHttpBaseUrlHostname: Schema.optionalKey(Schema.String),
+    expectedWsBaseUrlInputLength: Schema.Number,
+    expectedWsBaseUrlProtocol: Schema.optionalKey(Schema.String),
+    expectedWsBaseUrlHostname: Schema.optionalKey(Schema.String),
+    actualProviderKind: RelayManagedEndpointProviderKind,
+    actualHttpBaseUrlInputLength: Schema.Number,
+    actualHttpBaseUrlProtocol: Schema.optionalKey(Schema.String),
+    actualHttpBaseUrlHostname: Schema.optionalKey(Schema.String),
+    actualWsBaseUrlInputLength: Schema.Number,
+    actualWsBaseUrlProtocol: Schema.optionalKey(Schema.String),
+    actualWsBaseUrlHostname: Schema.optionalKey(Schema.String),
+  },
+) {
+  static fromEndpoints(input: {
+    readonly source: "environment status response" | "environment connect response";
+    readonly environmentId: string;
+    readonly expectedEndpoint: RelayClientEnvironmentRecord["endpoint"];
+    readonly actualEndpoint: RelayClientEnvironmentRecord["endpoint"];
+  }): CloudEnvironmentEndpointMismatchError {
+    const expectedHttp = getUrlDiagnostics(input.expectedEndpoint.httpBaseUrl);
+    const expectedWs = getUrlDiagnostics(input.expectedEndpoint.wsBaseUrl);
+    const actualHttp = getUrlDiagnostics(input.actualEndpoint.httpBaseUrl);
+    const actualWs = getUrlDiagnostics(input.actualEndpoint.wsBaseUrl);
+    return new CloudEnvironmentEndpointMismatchError({
+      source: input.source,
+      environmentId: input.environmentId,
+      expectedProviderKind: input.expectedEndpoint.providerKind,
+      expectedHttpBaseUrlInputLength: expectedHttp.inputLength,
+      ...(expectedHttp.protocol === undefined
+        ? {}
+        : { expectedHttpBaseUrlProtocol: expectedHttp.protocol }),
+      ...(expectedHttp.hostname === undefined
+        ? {}
+        : { expectedHttpBaseUrlHostname: expectedHttp.hostname }),
+      expectedWsBaseUrlInputLength: expectedWs.inputLength,
+      ...(expectedWs.protocol === undefined
+        ? {}
+        : { expectedWsBaseUrlProtocol: expectedWs.protocol }),
+      ...(expectedWs.hostname === undefined
+        ? {}
+        : { expectedWsBaseUrlHostname: expectedWs.hostname }),
+      actualProviderKind: input.actualEndpoint.providerKind,
+      actualHttpBaseUrlInputLength: actualHttp.inputLength,
+      ...(actualHttp.protocol === undefined
+        ? {}
+        : { actualHttpBaseUrlProtocol: actualHttp.protocol }),
+      ...(actualHttp.hostname === undefined
+        ? {}
+        : { actualHttpBaseUrlHostname: actualHttp.hostname }),
+      actualWsBaseUrlInputLength: actualWs.inputLength,
+      ...(actualWs.protocol === undefined ? {} : { actualWsBaseUrlProtocol: actualWs.protocol }),
+      ...(actualWs.hostname === undefined ? {} : { actualWsBaseUrlHostname: actualWs.hostname }),
     });
-  };
-}
+  }
 
-function findEnvironmentCloudApiError(cause: unknown): { readonly message: string } | null {
-  if (isEnvironmentCloudApiError(cause)) {
-    return cause;
+  override get message(): string {
+    return `The ${this.source} returned a different endpoint for environment "${this.environmentId}".`;
   }
-  if (typeof cause !== "object" || cause === null) {
-    return null;
+}
+
+export class CloudEnvironmentEndpointProviderMismatchError extends Schema.TaggedErrorClass<CloudEnvironmentEndpointProviderMismatchError>()(
+  "CloudEnvironmentEndpointProviderMismatchError",
+  {
+    environmentId: Schema.String,
+    expectedProviderKind: RelayManagedEndpointProviderKind,
+    actualProviderKind: RelayManagedEndpointProviderKind,
+  },
+) {
+  override get message(): string {
+    return `Relay returned link credentials with endpoint provider "${this.actualProviderKind}" instead of "${this.expectedProviderKind}".`;
   }
-  return "cause" in cause ? findEnvironmentCloudApiError(cause.cause) : null;
 }
 
+export const CloudEnvironmentLinkError = Schema.Union([
+  CloudEnvironmentLinkOperationError,
+  CloudRelayUrlNotConfiguredError,
+  CloudEnvironmentLocalBearerRequiredError,
+  CloudEnvironmentIdMismatchError,
+  CloudEnvironmentEndpointMismatchError,
+  CloudEnvironmentEndpointProviderMismatchError,
+]);
+export type CloudEnvironmentLinkError = typeof CloudEnvironmentLinkError.Type;
+export const isCloudEnvironmentLinkError = Schema.is(CloudEnvironmentLinkError);
+
+export interface CloudEnvironmentRecordWithStatus {
+  readonly environment: RelayClientEnvironmentRecord;
+  readonly status: RelayEnvironmentStatusResponseType | null;
+  readonly statusError: string | null;
+}
+
+const MANAGED_ENDPOINT_PROVIDER_KIND =
+  "cloudflare_tunnel" satisfies RelayManagedEndpointProviderKind;
+
 function requireRelayUrl(): Effect.Effect<string, CloudEnvironmentLinkError> {
   const relayUrl = readRelayUrl();
-  return relayUrl
-    ? Effect.succeed(relayUrl)
-    : Effect.fail(new CloudEnvironmentLinkError({ message: "Relay URL is not configured." }));
+  return relayUrl ? Effect.succeed(relayUrl) : Effect.fail(new CloudRelayUrlNotConfiguredError());
 }
 
-function endpointOrigin(httpBaseUrl: string) {
-  const url = new URL(httpBaseUrl);
-  return {
-    localHttpHost: "127.0.0.1",
-    localHttpPort: Number(url.port || (url.protocol === "https:" ? 443 : 80)),
-  };
+function endpointOrigin(input: { readonly environmentId: string; readonly httpBaseUrl: string }) {
+  return Effect.try({
+    try: () => {
+      const url = new URL(input.httpBaseUrl);
+      return {
+        localHttpHost: "127.0.0.1",
+        localHttpPort: Number(url.port || (url.protocol === "https:" ? 443 : 80)),
+      };
+    },
+    catch: (cause) =>
+      CloudEnvironmentLinkOperationError.fromCause({
+        action: "derive the environment endpoint origin",
+        environmentId: input.environmentId,
+        httpBaseUrl: input.httpBaseUrl,
+        cause,
+      }),
+  });
+}
+
+function makeCloudEnvironmentHttpApiClient(input: {
+  readonly environmentId: string;
+  readonly httpBaseUrl: string;
+}) {
+  return Effect.try({
+    try: () => makeEnvironmentHttpApiClient(input.httpBaseUrl),
+    catch: (cause) =>
+      CloudEnvironmentLinkOperationError.fromCause({
+        action: "initialize the environment HTTP client",
+        environmentId: input.environmentId,
+        httpBaseUrl: input.httpBaseUrl,
+        cause,
+      }),
+  }).pipe(Effect.flatten);
 }
 
 function ensureLinkedEnvironmentMatches(input: {
@@ -196,13 +368,17 @@ function ensureLinkedEnvironmentMatches(input: {
   readonly link: RelayEnvironmentLinkResponseType;
 }): Effect.Effect<void, CloudEnvironmentLinkError> {
   if (input.link.environmentId !== input.expectedEnvironmentId) {
-    return new CloudEnvironmentLinkError({
-      message: "Relay returned credentials for a different environment.",
+    return new CloudEnvironmentIdMismatchError({
+      source: "environment link response",
+      expectedEnvironmentId: input.expectedEnvironmentId,
+      actualEnvironmentId: input.link.environmentId,
     });
   }
   if (input.link.endpoint.providerKind !== input.expectedProviderKind) {
-    return new CloudEnvironmentLinkError({
-      message: "Relay returned credentials for a different endpoint provider.",
+    return new CloudEnvironmentEndpointProviderMismatchError({
+      environmentId: input.expectedEnvironmentId,
+      expectedProviderKind: input.expectedProviderKind,
+      actualProviderKind: input.link.endpoint.providerKind,
     });
   }
   return Effect.void;
@@ -224,21 +400,28 @@ function ensureStatusMatchesEnvironment(input: {
   readonly status: RelayEnvironmentStatusResponseType;
 }): Effect.Effect<void, CloudEnvironmentLinkError> {
   if (input.status.environmentId !== input.environment.environmentId) {
-    return new CloudEnvironmentLinkError({
-      message: "Relay returned status for a different environment.",
+    return new CloudEnvironmentIdMismatchError({
+      source: "environment status response",
+      expectedEnvironmentId: input.environment.environmentId,
+      actualEnvironmentId: input.status.environmentId,
     });
   }
   if (!endpointMatches(input.status.endpoint, input.environment.endpoint)) {
-    return new CloudEnvironmentLinkError({
-      message: "Relay returned status for a different endpoint.",
+    return CloudEnvironmentEndpointMismatchError.fromEndpoints({
+      source: "environment status response",
+      environmentId: input.environment.environmentId,
+      expectedEndpoint: input.environment.endpoint,
+      actualEndpoint: input.status.endpoint,
     });
   }
   if (
     input.status.descriptor &&
     input.status.descriptor.environmentId !== input.environment.environmentId
   ) {
-    return new CloudEnvironmentLinkError({
-      message: "Relay returned status descriptor for a different environment.",
+    return new CloudEnvironmentIdMismatchError({
+      source: "environment status descriptor",
+      expectedEnvironmentId: input.environment.environmentId,
+      actualEnvironmentId: input.status.descriptor.environmentId,
     });
   }
   return Effect.void;
@@ -249,8 +432,11 @@ function ensureConnectEndpointMatchesEnvironment(input: {
   readonly connect: RelayEnvironmentConnectResponseType;
 }): Effect.Effect<void, CloudEnvironmentLinkError> {
   if (!endpointMatches(input.connect.endpoint, input.environment.endpoint)) {
-    return new CloudEnvironmentLinkError({
-      message: "Relay returned credentials for a different endpoint.",
+    return CloudEnvironmentEndpointMismatchError.fromEndpoints({
+      source: "environment connect response",
+      environmentId: input.environment.environmentId,
+      expectedEndpoint: input.environment.endpoint,
+      actualEndpoint: input.connect.endpoint,
     });
   }
   return Effect.void;
@@ -266,8 +452,9 @@ export function linkEnvironmentToCloud(input: {
 > {
   return Effect.gen(function* () {
     if (!input.connection.bearerToken) {
-      return yield* new CloudEnvironmentLinkError({
-        message: "Only a locally paired bearer connection can be linked to the cloud.",
+      return yield* CloudEnvironmentLocalBearerRequiredError.fromConnection({
+        environmentId: input.connection.environmentId,
+        httpBaseUrl: input.connection.httpBaseUrl,
       });
     }
     const localBearerToken = input.connection.bearerToken;
@@ -275,11 +462,21 @@ export function linkEnvironmentToCloud(input: {
     const relayClient = yield* ManagedRelay.ManagedRelayClient;
     const deviceId = yield* Effect.tryPromise({
       try: () => loadOrCreateAgentAwarenessDeviceId(),
-      catch: cloudEnvironmentLinkError("Could not load the mobile device id."),
+      catch: (cause) =>
+        CloudEnvironmentLinkOperationError.fromCause({
+          action: "load the mobile device id",
+          environmentId: input.connection.environmentId,
+          cause,
+        }),
     });
     const preferences = yield* Effect.tryPromise({
       try: () => loadPreferences(),
-      catch: cloudEnvironmentLinkError("Could not load mobile notification preferences."),
+      catch: (cause) =>
+        CloudEnvironmentLinkOperationError.fromCause({
+          action: "load mobile notification preferences",
+          environmentId: input.connection.environmentId,
+          cause,
+        }),
     });
     const liveActivitiesEnabled = preferences.liveActivitiesEnabled !== false;
     const challenge = yield* relayClient
@@ -292,11 +489,23 @@ export function linkEnvironmentToCloud(input: {
         },
       })
       .pipe(
-        Effect.mapError(
-          decodedRelayClientError(`${relayUrl}/v1/client/environment-link-challenges failed`),
+        Effect.mapError((cause) =>
+          CloudEnvironmentLinkOperationError.fromCause({
+            action: "create an environment link challenge",
+            environmentId: input.connection.environmentId,
+            relayUrl,
+            cause,
+          }),
         ),
       );
-    const environmentClient = yield* makeEnvironmentHttpApiClient(input.connection.httpBaseUrl);
+    const origin = yield* endpointOrigin({
+      environmentId: input.connection.environmentId,
+      httpBaseUrl: input.connection.httpBaseUrl,
+    });
+    const environmentClient = yield* makeCloudEnvironmentHttpApiClient({
+      environmentId: input.connection.environmentId,
+      httpBaseUrl: input.connection.httpBaseUrl,
+    });
     const proof = yield* environmentClient.connect
       .linkProof({
         headers: { authorization: `Bearer ${localBearerToken}` },
@@ -308,10 +517,19 @@ export function linkEnvironmentToCloud(input: {
             wsBaseUrl: input.connection.wsBaseUrl,
             providerKind: MANAGED_ENDPOINT_PROVIDER_KIND,
           },
-          origin: endpointOrigin(input.connection.httpBaseUrl),
+          origin,
         },
       })
-      .pipe(Effect.mapError(cloudEnvironmentLinkError("Could not obtain environment link proof.")));
+      .pipe(
+        Effect.mapError((cause) =>
+          CloudEnvironmentLinkOperationError.fromCause({
+            action: "obtain an environment link proof",
+            environmentId: input.connection.environmentId,
+            httpBaseUrl: input.connection.httpBaseUrl,
+            cause,
+          }),
+        ),
+      );
     const link = yield* relayClient
       .linkEnvironment({
         clerkToken: input.clerkToken,
@@ -324,7 +542,14 @@ export function linkEnvironmentToCloud(input: {
         },
       })
       .pipe(
-        Effect.mapError(decodedRelayClientError(`${relayUrl}/v1/client/environment-links failed`)),
+        Effect.mapError((cause) =>
+          CloudEnvironmentLinkOperationError.fromCause({
+            action: "link the environment",
+            environmentId: input.connection.environmentId,
+            relayUrl,
+            cause,
+          }),
+        ),
       );
     yield* ensureLinkedEnvironmentMatches({
       expectedEnvironmentId: input.connection.environmentId,
@@ -345,7 +570,14 @@ export function linkEnvironmentToCloud(input: {
         },
       })
       .pipe(
-        Effect.mapError(cloudEnvironmentLinkError("Could not configure environment relay access.")),
+        Effect.mapError((cause) =>
+          CloudEnvironmentLinkOperationError.fromCause({
+            action: "configure environment relay access",
+            environmentId: input.connection.environmentId,
+            httpBaseUrl: input.connection.httpBaseUrl,
+            cause,
+          }),
+        ),
       );
   });
 }
@@ -361,11 +593,15 @@ export function listCloudEnvironments(input: {
     const relayUrl = yield* requireRelayUrl();
     const relayClient = yield* ManagedRelay.ManagedRelayClient;
 
-    return yield* relayClient
-      .listEnvironments({
-        clerkToken: input.clerkToken,
-      })
-      .pipe(Effect.mapError(decodedRelayClientError(`${relayUrl}/v1/environments failed`)));
+    return yield* relayClient.listEnvironments({ clerkToken: input.clerkToken }).pipe(
+      Effect.mapError((cause) =>
+        CloudEnvironmentLinkOperationError.fromCause({
+          action: "list cloud environments",
+          relayUrl,
+          cause,
+        }),
+      ),
+    );
   });
 }
 
@@ -388,10 +624,13 @@ export function getCloudEnvironmentStatus(input: {
         environmentId: input.environment.environmentId,
       })
       .pipe(
-        Effect.mapError(
-          decodedRelayClientError(
-            `${relayUrl}/v1/environments/${encodeURIComponent(input.environment.environmentId)}/status failed`,
-          ),
+        Effect.mapError((cause) =>
+          CloudEnvironmentLinkOperationError.fromCause({
+            action: "read cloud environment status",
+            environmentId: input.environment.environmentId,
+            relayUrl,
+            cause,
+          }),
         ),
       );
     yield* ensureStatusMatchesEnvironment({ environment: input.environment, status });
@@ -458,14 +697,19 @@ export function listCloudEnvironmentsWithStatus(input: {
   });
 }
 
-const loadAgentAwarenessDeviceId = Effect.fn("mobile.cloud.loadAgentAwarenessDeviceId")(
-  function* () {
-    return yield* Effect.tryPromise({
-      try: () => loadOrCreateAgentAwarenessDeviceId(),
-      catch: cloudEnvironmentLinkError("Could not load the mobile device id."),
-    });
-  },
-);
+const loadAgentAwarenessDeviceId = Effect.fn("mobile.cloud.loadAgentAwarenessDeviceId")(function* (
+  environmentId: string,
+) {
+  return yield* Effect.tryPromise({
+    try: () => loadOrCreateAgentAwarenessDeviceId(),
+    catch: (cause) =>
+      CloudEnvironmentLinkOperationError.fromCause({
+        action: "load the mobile device id",
+        environmentId,
+        cause,
+      }),
+  });
+});
 
 const connectRelayManagedEnvironment = Effect.fn("mobile.cloud.connectRelayManagedEnvironment")(
   function* (input: {
@@ -477,7 +721,7 @@ const connectRelayManagedEnvironment = Effect.fn("mobile.cloud.connectRelayManag
     const relayUrl = yield* requireRelayUrl();
     const relayClient = yield* ManagedRelay.ManagedRelayClient;
 
-    const deviceId = yield* loadAgentAwarenessDeviceId();
+    const deviceId = yield* loadAgentAwarenessDeviceId(input.environmentId);
     const connect = yield* relayClient
       .connectEnvironment({
         clerkToken: input.clerkToken,
@@ -486,15 +730,20 @@ const connectRelayManagedEnvironment = Effect.fn("mobile.cloud.connectRelayManag
         deviceId,
       })
       .pipe(
-        Effect.mapError(
-          decodedRelayClientError(
-            `${relayUrl}/v1/environments/${encodeURIComponent(input.environmentId)}/connect failed`,
-          ),
+        Effect.mapError((cause) =>
+          CloudEnvironmentLinkOperationError.fromCause({
+            action: "connect to the cloud environment",
+            environmentId: input.environmentId,
+            relayUrl,
+            cause,
+          }),
         ),
       );
     if (connect.environmentId !== input.environmentId) {
-      return yield* new CloudEnvironmentLinkError({
-        message: "Relay returned credentials for a different environment.",
+      return yield* new CloudEnvironmentIdMismatchError({
+        source: "environment connect response",
+        expectedEnvironmentId: input.environmentId,
+        actualEnvironmentId: connect.environmentId,
       });
     }
     if (input.expectedEnvironment) {
@@ -507,39 +756,69 @@ const connectRelayManagedEnvironment = Effect.fn("mobile.cloud.connectRelayManag
     const descriptor = yield* fetchRemoteEnvironmentDescriptor({
       httpBaseUrl: connect.endpoint.httpBaseUrl,
     }).pipe(
-      Effect.mapError(
-        cloudEnvironmentLinkError("Could not fetch the connected environment descriptor."),
+      Effect.mapError((cause) =>
+        CloudEnvironmentLinkOperationError.fromCause({
+          action: "fetch the connected environment descriptor",
+          environmentId: input.environmentId,
+          httpBaseUrl: connect.endpoint.httpBaseUrl,
+          cause,
+        }),
       ),
     );
     if (descriptor.environmentId !== connect.environmentId) {
-      return yield* new CloudEnvironmentLinkError({
-        message: "Connected endpoint descriptor does not match the selected environment.",
+      return yield* new CloudEnvironmentIdMismatchError({
+        source: "connected environment descriptor",
+        expectedEnvironmentId: connect.environmentId,
+        actualEnvironmentId: descriptor.environmentId,
       });
     }
+    const endpointUrl = yield* Effect.try({
+      try: () => new URL(connect.endpoint.httpBaseUrl),
+      catch: (cause) =>
+        CloudEnvironmentLinkOperationError.fromCause({
+          action: "parse the managed endpoint URL",
+          environmentId: input.environmentId,
+          httpBaseUrl: connect.endpoint.httpBaseUrl,
+          cause,
+        }),
+    });
     const signer = yield* ManagedRelay.ManagedRelayDpopSigner;
     const bootstrapDpop = yield* signer
       .createProof({
         method: "POST",
-        url: new URL("/oauth/token", connect.endpoint.httpBaseUrl).toString(),
+        url: new URL("/oauth/token", endpointUrl).toString(),
       })
-      .pipe(Effect.mapError(cloudEnvironmentLinkError("Could not create bootstrap DPoP proof.")));
+      .pipe(
+        Effect.mapError((cause) =>
+          CloudEnvironmentLinkOperationError.fromCause({
+            action: "create a bootstrap DPoP proof",
+            environmentId: input.environmentId,
+            httpBaseUrl: connect.endpoint.httpBaseUrl,
+            cause,
+          }),
+        ),
+      );
     const bootstrap = yield* exchangeRemoteDpopAccessToken({
       httpBaseUrl: connect.endpoint.httpBaseUrl,
       credential: connect.credential,
       dpopProof: bootstrapDpop,
       clientMetadata: authClientMetadata(),
     }).pipe(
-      Effect.mapError(
-        cloudEnvironmentLinkError("Could not exchange a managed endpoint DPoP access token."),
+      Effect.mapError((cause) =>
+        CloudEnvironmentLinkOperationError.fromCause({
+          action: "exchange a managed endpoint DPoP access token",
+          environmentId: input.environmentId,
+          httpBaseUrl: connect.endpoint.httpBaseUrl,
+          cause,
+        }),
       ),
     );
-    const pairingUrl = new URL(connect.endpoint.httpBaseUrl);
-    pairingUrl.hash = new URLSearchParams([["token", connect.credential]]).toString();
+    endpointUrl.hash = new URLSearchParams([["token", connect.credential]]).toString();
 
     return {
       environmentId: descriptor.environmentId,
       environmentLabel: descriptor.label,
-      pairingUrl: stripPairingTokenFromUrl(pairingUrl).toString(),
+      pairingUrl: stripPairingTokenFromUrl(endpointUrl).toString(),
       displayUrl: connect.endpoint.httpBaseUrl,
       httpBaseUrl: connect.endpoint.httpBaseUrl,
       wsBaseUrl: connect.endpoint.wsBaseUrl,
diff --git a/apps/mobile/src/features/cloud/managedRelayLayer.ts b/apps/mobile/src/features/cloud/managedRelayLayer.ts
index 2da1fa9157c..9014a5e2cab 100644
--- a/apps/mobile/src/features/cloud/managedRelayLayer.ts
+++ b/apps/mobile/src/features/cloud/managedRelayLayer.ts
@@ -28,25 +28,24 @@ const relayDpopSignerLayer = Layer.effect(
       ),
       createProof: Effect.fn("mobile.managedRelayDpopSigner.createProof")(function* (input) {
         const proofKey = yield* loadProofKey.pipe(
-          Effect.mapError(
-            (error) =>
-              new ManagedRelay.ManagedRelayDpopProofCreationError({
-                method: input.method,
-                url: input.url,
-                cause: error,
-              }),
+          Effect.mapError((error) =>
+            ManagedRelay.ManagedRelayDpopKeyLoadError.fromTarget({
+              keyStore: "expo-secure-store",
+              method: input.method,
+              url: input.url,
+              cause: error,
+            }),
           ),
         );
         return yield* createDpopProof({ ...input, proofKey }).pipe(
           Effect.provideService(Crypto.Crypto, crypto),
           Effect.map((proof) => proof.proof),
-          Effect.mapError(
-            (error) =>
-              new ManagedRelay.ManagedRelayDpopProofCreationError({
-                method: input.method,
-                url: input.url,
-                cause: error,
-              }),
+          Effect.mapError((error) =>
+            ManagedRelay.ManagedRelayDpopProofCreationError.fromTarget({
+              method: input.method,
+              url: input.url,
+              cause: error,
+            }),
           ),
         );
       }),
diff --git a/apps/mobile/src/features/connection/useConnectionController.ts b/apps/mobile/src/features/connection/useConnectionController.ts
index bad6b6f1720..fa3b2a52302 100644
--- a/apps/mobile/src/features/connection/useConnectionController.ts
+++ b/apps/mobile/src/features/connection/useConnectionController.ts
@@ -58,7 +58,7 @@ export function useConnectionController() {
         environment: entry.environment,
         availability: entry.availability,
         status: Option.getOrNull(entry.status),
-        error: Option.getOrNull(entry.error)?.message ?? null,
+        error: Option.getOrNull(entry.error)?.detail ?? null,
         traceId: Option.getOrNull(entry.error)?.traceId ?? null,
       })),
     [discovery.environments],
@@ -112,7 +112,7 @@ export function useConnectionController() {
     relayDiscovery: {
       isRefreshing: discovery.refreshing,
       isOffline: discovery.offline,
-      error: Option.getOrNull(discovery.error)?.message ?? null,
+      error: Option.getOrNull(discovery.error)?.detail ?? null,
       errorTraceId: Option.getOrNull(discovery.error)?.traceId ?? null,
     },
     connectPairingUrl,
diff --git a/apps/mobile/src/features/files/sourceHighlightingState.test.ts b/apps/mobile/src/features/files/sourceHighlightingState.test.ts
index 6c4c00e1663..23b5334d9b1 100644
--- a/apps/mobile/src/features/files/sourceHighlightingState.test.ts
+++ b/apps/mobile/src/features/files/sourceHighlightingState.test.ts
@@ -1,9 +1,11 @@
+import * as Cause from "effect/Cause";
 import { AtomRegistry } from "effect/unstable/reactivity";
 import * as AsyncResult from "effect/unstable/reactivity/AsyncResult";
 import { afterEach, describe, expect, it, vi } from "vite-plus/test";
 
 import {
   createSourceHighlightAtomFamily,
+  SourceHighlightError,
   type SourceHighlightTokens,
 } from "./sourceHighlightingState";
 
@@ -100,22 +102,29 @@ describe("sourceHighlightingState", () => {
     registry.dispose();
   });
 
-  it("exposes highlighter errors as a failed async result", async () => {
-    const highlight = vi.fn(async () => {
-      throw new Error("highlight failed");
-    });
+  it("preserves highlighter failures with the source path and theme", async () => {
+    const cause = new Error("highlight failed");
+    const highlight = vi.fn(() => Promise.reject(cause));
     const sourceHighlightAtom = createSourceHighlightAtomFamily({ highlight });
     const registry = AtomRegistry.make();
+    const path = "src/example.ts";
+    const theme = "light" as const;
     const atom = sourceHighlightAtom({
-      path: "src/example.ts",
+      path,
       contents: "const value = 1;",
-      theme: "light",
+      theme,
     });
     const unmount = registry.mount(atom);
 
     await vi.waitFor(() => {
       expect(AsyncResult.isFailure(registry.get(atom))).toBe(true);
     });
+    const result = registry.get(atom);
+    if (AsyncResult.isFailure(result)) {
+      const error = Cause.squash(result.cause);
+      expect(error).toEqual(new SourceHighlightError({ path, theme, cause }));
+      expect((error as SourceHighlightError).cause).toBe(cause);
+    }
 
     unmount();
     registry.dispose();
diff --git a/apps/mobile/src/features/files/sourceHighlightingState.ts b/apps/mobile/src/features/files/sourceHighlightingState.ts
index 43363115bc8..45506d1cfcf 100644
--- a/apps/mobile/src/features/files/sourceHighlightingState.ts
+++ b/apps/mobile/src/features/files/sourceHighlightingState.ts
@@ -1,5 +1,6 @@
 import * as Data from "effect/Data";
 import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
 import { Atom } from "effect/unstable/reactivity";
 
 import {
@@ -22,9 +23,18 @@ type SourceHighlighter = (input: SourceHighlightInput) => Promise<SourceHighligh
 
 class SourceHighlightCacheKey extends Data.Class<SourceHighlightInput> {}
 
-class SourceHighlightError extends Data.TaggedError("SourceHighlightError")<{
-  readonly cause: unknown;
-}> {}
+export class SourceHighlightError extends Schema.TaggedErrorClass<SourceHighlightError>()(
+  "SourceHighlightError",
+  {
+    path: Schema.String,
+    theme: Schema.Literals(["light", "dark"]),
+    cause: Schema.Defect(),
+  },
+) {
+  override get message(): string {
+    return `Could not highlight ${this.path} with the ${this.theme} theme.`;
+  }
+}
 
 export function createSourceHighlightAtomFamily(options?: {
   readonly highlight?: SourceHighlighter;
@@ -36,7 +46,8 @@ export function createSourceHighlightAtomFamily(options?: {
     Atom.make(
       Effect.tryPromise({
         try: () => highlight(request),
-        catch: (cause) => new SourceHighlightError({ cause }),
+        catch: (cause) =>
+          new SourceHighlightError({ path: request.path, theme: request.theme, cause }),
       }),
     ).pipe(
       Atom.setIdleTTL(idleTtlMs),
diff --git a/apps/mobile/src/features/files/workspace-file-image-cache.test.ts b/apps/mobile/src/features/files/workspace-file-image-cache.test.ts
index 4acb67361a8..3764d4b29d0 100644
--- a/apps/mobile/src/features/files/workspace-file-image-cache.test.ts
+++ b/apps/mobile/src/features/files/workspace-file-image-cache.test.ts
@@ -1,8 +1,14 @@
+import * as Cause from "effect/Cause";
+import * as Hash from "effect/Hash";
 import { AtomRegistry } from "effect/unstable/reactivity";
 import * as AsyncResult from "effect/unstable/reactivity/AsyncResult";
 import { describe, expect, it, vi } from "vite-plus/test";
 
-import { createWorkspaceFileImageAtomFamily } from "./workspace-file-image-cache";
+import {
+  createWorkspaceFileImageAtomFamily,
+  WorkspaceImagePrefetchFailedError,
+  WorkspaceImagePrefetchUnavailableError,
+} from "./workspace-file-image-cache";
 
 describe("workspaceFileImageAtom", () => {
   it("reuses a prefetched image across route remounts", async () => {
@@ -48,15 +54,65 @@ describe("workspaceFileImageAtom", () => {
     registry.dispose();
   });
 
-  it("exposes prefetch failures", async () => {
+  it("reports an unavailable image when prefetch completes without caching it", async () => {
+    const uri = "https://example.test/api/assets/signed-secret-token/missing.png?signature=private";
     const imageAtom = createWorkspaceFileImageAtomFamily({ prefetch: async () => false });
     const registry = AtomRegistry.make();
-    const atom = imageAtom("https://example.test/missing.png");
+    const atom = imageAtom(uri);
+    expect(atom.label?.[0]).not.toContain("signed-secret-token");
+    expect(atom.label?.[0]).not.toContain("signature=private");
     const unmount = registry.mount(atom);
 
     await vi.waitFor(() => {
       expect(AsyncResult.isFailure(registry.get(atom))).toBe(true);
     });
+    const result = registry.get(atom);
+    if (AsyncResult.isFailure(result)) {
+      const error = Cause.squash(result.cause);
+      expect(error).toEqual(
+        new WorkspaceImagePrefetchUnavailableError({
+          uriHash: Hash.hash(uri),
+          uriLength: uri.length,
+          uriProtocol: "https:",
+        }),
+      );
+      expect(error).not.toHaveProperty("uri");
+      expect(String(error)).not.toContain("signed-secret-token");
+      expect(String(error)).not.toContain("signature=private");
+    }
+
+    unmount();
+    registry.dispose();
+  });
+
+  it("preserves rejected prefetch causes without retaining the signed image URI", async () => {
+    const uri =
+      "https://example.test/api/assets/signed-secret-token/rejected.png?signature=private";
+    const cause = new Error("native image loader failed");
+    const imageAtom = createWorkspaceFileImageAtomFamily({ prefetch: () => Promise.reject(cause) });
+    const registry = AtomRegistry.make();
+    const atom = imageAtom(uri);
+    const unmount = registry.mount(atom);
+
+    await vi.waitFor(() => {
+      expect(AsyncResult.isFailure(registry.get(atom))).toBe(true);
+    });
+    const result = registry.get(atom);
+    if (AsyncResult.isFailure(result)) {
+      const error = Cause.squash(result.cause);
+      expect(error).toEqual(
+        new WorkspaceImagePrefetchFailedError({
+          uriHash: Hash.hash(uri),
+          uriLength: uri.length,
+          uriProtocol: "https:",
+          cause,
+        }),
+      );
+      expect((error as WorkspaceImagePrefetchFailedError).cause).toBe(cause);
+      expect(error).not.toHaveProperty("uri");
+      expect(String(error)).not.toContain("signed-secret-token");
+      expect(String(error)).not.toContain("signature=private");
+    }
 
     unmount();
     registry.dispose();
diff --git a/apps/mobile/src/features/files/workspace-file-image-cache.ts b/apps/mobile/src/features/files/workspace-file-image-cache.ts
index 3f58f65b46c..9251f57185c 100644
--- a/apps/mobile/src/features/files/workspace-file-image-cache.ts
+++ b/apps/mobile/src/features/files/workspace-file-image-cache.ts
@@ -1,5 +1,8 @@
+import { getUrlDiagnostics } from "@t3tools/shared/urlDiagnostics";
 import * as Data from "effect/Data";
 import * as Effect from "effect/Effect";
+import * as Hash from "effect/Hash";
+import * as Schema from "effect/Schema";
 import { Atom } from "effect/unstable/reactivity";
 
 const WORKSPACE_IMAGE_IDLE_TTL_MS = 30 * 60_000;
@@ -8,39 +11,77 @@ type ImagePrefetch = (uri: string) => Promise<boolean>;
 
 class WorkspaceImageCacheKey extends Data.Class<{ readonly uri: string }> {}
 
-export class WorkspaceImagePrefetchError extends Data.TaggedError("WorkspaceImagePrefetchError")<{
-  readonly cause?: unknown;
-  readonly uri: string;
-}> {}
+export class WorkspaceImagePrefetchUnavailableError extends Schema.TaggedErrorClass<WorkspaceImagePrefetchUnavailableError>()(
+  "WorkspaceImagePrefetchUnavailableError",
+  {
+    uriHash: Schema.Number,
+    uriLength: Schema.Number,
+    uriProtocol: Schema.NullOr(Schema.String),
+  },
+) {
+  override get message(): string {
+    return `Image prefetch did not cache the requested ${this.uriProtocol ?? "unknown-protocol"} resource (URI length ${this.uriLength}).`;
+  }
+}
+
+export class WorkspaceImagePrefetchFailedError extends Schema.TaggedErrorClass<WorkspaceImagePrefetchFailedError>()(
+  "WorkspaceImagePrefetchFailedError",
+  {
+    uriHash: Schema.Number,
+    uriLength: Schema.Number,
+    uriProtocol: Schema.NullOr(Schema.String),
+    cause: Schema.Defect(),
+  },
+) {
+  override get message(): string {
+    return `Image prefetch failed for the requested ${this.uriProtocol ?? "unknown-protocol"} resource (URI length ${this.uriLength}).`;
+  }
+}
+
+export const WorkspaceImagePrefetchError = Schema.Union([
+  WorkspaceImagePrefetchUnavailableError,
+  WorkspaceImagePrefetchFailedError,
+]);
+export type WorkspaceImagePrefetchError = typeof WorkspaceImagePrefetchError.Type;
 
 async function prefetchWithNativeImage(uri: string): Promise<boolean> {
   const { Image } = await import("react-native");
   return Image.prefetch(uri);
 }
 
+function describeWorkspaceImageUri(uri: string) {
+  const diagnostics = getUrlDiagnostics(uri);
+  return {
+    uriHash: Hash.hash(uri),
+    uriLength: diagnostics.inputLength,
+    uriProtocol: diagnostics.protocol ?? null,
+  };
+}
+
 export function createWorkspaceFileImageAtomFamily(options?: {
   readonly idleTtlMs?: number;
   readonly prefetch?: ImagePrefetch;
 }) {
   const idleTtlMs = options?.idleTtlMs ?? WORKSPACE_IMAGE_IDLE_TTL_MS;
   const prefetch = options?.prefetch ?? prefetchWithNativeImage;
-  const family = Atom.family((key: WorkspaceImageCacheKey) =>
-    Atom.make(
-      Effect.tryPromise({
-        try: async () => {
-          const cached = await prefetch(key.uri);
-          if (!cached) {
-            throw new WorkspaceImagePrefetchError({ uri: key.uri });
-          }
-          return key.uri;
-        },
-        catch: (cause) =>
-          cause instanceof WorkspaceImagePrefetchError
-            ? cause
-            : new WorkspaceImagePrefetchError({ uri: key.uri, cause }),
+  const family = Atom.family((key: WorkspaceImageCacheKey) => {
+    const uriContext = describeWorkspaceImageUri(key.uri);
+    return Atom.make(
+      Effect.gen(function* () {
+        const cached = yield* Effect.tryPromise({
+          try: () => prefetch(key.uri),
+          catch: (cause) => new WorkspaceImagePrefetchFailedError({ ...uriContext, cause }),
+        });
+        if (!cached) {
+          return yield* new WorkspaceImagePrefetchUnavailableError(uriContext);
+        }
+        return key.uri;
       }),
-    ).pipe(Atom.setIdleTTL(idleTtlMs), Atom.withLabel(`mobile:workspace-image:${key.uri}`)),
-  );
+    ).pipe(
+      Atom.setIdleTTL(idleTtlMs),
+      Atom.withLabel(`mobile:workspace-image:${uriContext.uriHash.toString(36)}`),
+    );
+  });
 
   return (uri: string) => family(new WorkspaceImageCacheKey({ uri }));
 }
diff --git a/apps/mobile/src/lib/composerImages.test.ts b/apps/mobile/src/lib/composerImages.test.ts
index 40e00a271f7..0e047fee842 100644
--- a/apps/mobile/src/lib/composerImages.test.ts
+++ b/apps/mobile/src/lib/composerImages.test.ts
@@ -1,6 +1,7 @@
 import { beforeEach, describe, expect, it, vi } from "vite-plus/test";
 import { PROVIDER_SEND_TURN_MAX_ATTACHMENTS } from "@t3tools/contracts";
 
+const missingFileCause = new Error("missing file");
 const files = new Map<string, { base64: string; deleted: boolean }>();
 
 vi.mock("expo-file-system", () => ({
@@ -18,7 +19,7 @@ vi.mock("expo-file-system", () => ({
     async base64(): Promise<string> {
       const entry = files.get(this.uri);
       if (!entry || entry.deleted) {
-        throw new Error("missing file");
+        throw missingFileCause;
       }
       return entry.base64;
     }
@@ -91,4 +92,30 @@ describe("native pasted image cleanup", () => {
     expect(files.get(overflow)?.deleted).toBe(true);
     expect(files.get(userOwned)?.deleted).toBe(false);
   });
+
+  it("reports structured context when reading a pasted image fails", async () => {
+    const uri = "file:///private/var/mobile/photos/signed-secret-token/missing.png?token=private";
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+
+    await expect(
+      convertPastedImagesToAttachments({ uris: [uri], existingCount: 0 }),
+    ).resolves.toEqual([]);
+    expect(warn).toHaveBeenCalledWith(
+      "[composer-images] failed to read pasted image",
+      expect.objectContaining({
+        _tag: "ComposerImageOperationError",
+        operation: "read-pasted-image",
+        uriLength: uri.length,
+        uriProtocol: "file:",
+        cause: missingFileCause,
+        message: `Composer image operation read-pasted-image failed for a file: URI (length ${uri.length}).`,
+      }),
+    );
+    const error = warn.mock.calls[0]?.[1];
+    expect(error).not.toHaveProperty("uri");
+    expect(String(error)).not.toContain("signed-secret-token");
+    expect(String(error)).not.toContain("token=private");
+
+    warn.mockRestore();
+  });
 });
diff --git a/apps/mobile/src/lib/composerImages.ts b/apps/mobile/src/lib/composerImages.ts
index 13b53af724e..edb5f43dda3 100644
--- a/apps/mobile/src/lib/composerImages.ts
+++ b/apps/mobile/src/lib/composerImages.ts
@@ -3,6 +3,8 @@ import {
   PROVIDER_SEND_TURN_MAX_IMAGE_BYTES,
   type UploadChatImageAttachment,
 } from "@t3tools/contracts";
+import { getUrlDiagnostics } from "@t3tools/shared/urlDiagnostics";
+import * as Schema from "effect/Schema";
 import { uuidv4 } from "./uuid";
 
 export interface DraftComposerImageAttachment extends UploadChatImageAttachment {
@@ -12,6 +14,31 @@ export interface DraftComposerImageAttachment extends UploadChatImageAttachment
 
 const OWNED_PASTED_IMAGE_DIRECTORY = "t3-composer-paste";
 
+export class ComposerImageOperationError extends Schema.TaggedErrorClass<ComposerImageOperationError>()(
+  "ComposerImageOperationError",
+  {
+    operation: Schema.Literals([
+      "load-image-picker",
+      "request-media-library-permission",
+      "launch-image-library",
+      "load-clipboard",
+      "check-clipboard-image",
+      "read-clipboard-image",
+      "check-clipboard-text",
+      "read-clipboard-text",
+      "read-pasted-image",
+      "remove-pasted-image",
+    ]),
+    uriLength: Schema.optional(Schema.Number),
+    uriProtocol: Schema.optional(Schema.String),
+    cause: Schema.Defect(),
+  },
+) {
+  override get message(): string {
+    return `Composer image operation ${this.operation} failed${this.uriLength === undefined ? "" : ` for a ${this.uriProtocol ?? "unknown-protocol"} URI (length ${this.uriLength})`}.`;
+  }
+}
+
 function estimateBase64ByteSize(base64: string): number {
   const padding = base64.endsWith("==") ? 2 : base64.endsWith("=") ? 1 : 0;
   return Math.floor((base64.length * 3) / 4) - padding;
@@ -20,16 +47,22 @@ function estimateBase64ByteSize(base64: string): number {
 async function loadImagePicker() {
   try {
     return await import("expo-image-picker");
-  } catch (error) {
-    throw new Error("Image attachments are unavailable right now.", { cause: error });
+  } catch (cause) {
+    throw new ComposerImageOperationError({
+      operation: "load-image-picker",
+      cause,
+    });
   }
 }
 
 async function loadClipboard() {
   try {
     return await import("expo-clipboard");
-  } catch (error) {
-    throw new Error("Clipboard paste is unavailable right now.", { cause: error });
+  } catch (cause) {
+    throw new ComposerImageOperationError({
+      operation: "load-clipboard",
+      cause,
+    });
   }
 }
 
@@ -49,14 +82,19 @@ export async function pickComposerImages(input: { readonly existingCount: number
   try {
     imagePicker = await loadImagePicker();
   } catch (error) {
+    console.warn("[composer-images] image picker unavailable", error);
     return {
       images: [],
-      error:
-        error instanceof Error ? error.message : "Image attachments are unavailable right now.",
+      error: "Image attachments are unavailable right now.",
     };
   }
 
-  const permission = await imagePicker.requestMediaLibraryPermissionsAsync();
+  const permission = await imagePicker.requestMediaLibraryPermissionsAsync().catch((cause) => {
+    throw new ComposerImageOperationError({
+      operation: "request-media-library-permission",
+      cause,
+    });
+  });
   if (!permission.granted) {
     return {
       images: [],
@@ -64,13 +102,20 @@ export async function pickComposerImages(input: { readonly existingCount: number
     };
   }
 
-  const result = await imagePicker.launchImageLibraryAsync({
-    mediaTypes: ["images"],
-    allowsMultipleSelection: true,
-    selectionLimit: remainingSlots,
-    base64: true,
-    quality: 1,
-  });
+  const result = await imagePicker
+    .launchImageLibraryAsync({
+      mediaTypes: ["images"],
+      allowsMultipleSelection: true,
+      selectionLimit: remainingSlots,
+      base64: true,
+      quality: 1,
+    })
+    .catch((cause) => {
+      throw new ComposerImageOperationError({
+        operation: "launch-image-library",
+        cause,
+      });
+    });
 
   if (result.canceled) {
     return {
@@ -127,16 +172,23 @@ export async function pasteComposerClipboard(input: { readonly existingCount: nu
   try {
     clipboard = await loadClipboard();
   } catch (error) {
+    console.warn("[composer-images] clipboard unavailable", error);
     return {
       images: [],
       text: null,
-      error: error instanceof Error ? error.message : "Clipboard paste is unavailable right now.",
+      error: "Clipboard paste is unavailable right now.",
     };
   }
 
   const remainingSlots = PROVIDER_SEND_TURN_MAX_ATTACHMENTS - input.existingCount;
 
-  if (await clipboard.hasImageAsync()) {
+  const hasImage = await clipboard.hasImageAsync().catch((cause) => {
+    throw new ComposerImageOperationError({
+      operation: "check-clipboard-image",
+      cause,
+    });
+  });
+  if (hasImage) {
     if (remainingSlots <= 0) {
       return {
         images: [],
@@ -144,7 +196,12 @@ export async function pasteComposerClipboard(input: { readonly existingCount: nu
         error: `You can attach up to ${PROVIDER_SEND_TURN_MAX_ATTACHMENTS} images per message.`,
       };
     }
-    const image = await clipboard.getImageAsync({ format: "png" });
+    const image = await clipboard.getImageAsync({ format: "png" }).catch((cause) => {
+      throw new ComposerImageOperationError({
+        operation: "read-clipboard-image",
+        cause,
+      });
+    });
     if (!image) {
       return {
         images: [],
@@ -180,8 +237,19 @@ export async function pasteComposerClipboard(input: { readonly existingCount: nu
     };
   }
 
-  if (await clipboard.hasStringAsync()) {
-    const text = await clipboard.getStringAsync();
+  const hasText = await clipboard.hasStringAsync().catch((cause) => {
+    throw new ComposerImageOperationError({
+      operation: "check-clipboard-text",
+      cause,
+    });
+  });
+  if (hasText) {
+    const text = await clipboard.getStringAsync().catch((cause) => {
+      throw new ComposerImageOperationError({
+        operation: "read-clipboard-text",
+        cause,
+      });
+    });
     return {
       images: [],
       text: text.length > 0 ? text : null,
@@ -230,6 +298,14 @@ export function isOwnedPastedImageUri(uri: string): boolean {
   }
 }
 
+function describeComposerImageUri(uri: string) {
+  const diagnostics = getUrlDiagnostics(uri);
+  return {
+    uriLength: diagnostics.inputLength,
+    ...(diagnostics.protocol === undefined ? {} : { uriProtocol: diagnostics.protocol }),
+  };
+}
+
 export async function convertPastedImagesToAttachments(input: {
   readonly uris: ReadonlyArray<string>;
   readonly existingCount: number;
@@ -260,8 +336,15 @@ export async function convertPastedImagesToAttachments(input: {
         dataUrl: `data:${mimeType};base64,${base64}`,
         previewUri: ownedTemporaryFile ? `data:${mimeType};base64,${base64}` : uri,
       });
-    } catch (error) {
-      console.warn("Failed to read pasted image", uri, error);
+    } catch (cause) {
+      console.warn(
+        "[composer-images] failed to read pasted image",
+        new ComposerImageOperationError({
+          operation: "read-pasted-image",
+          ...describeComposerImageUri(uri),
+          cause,
+        }),
+      );
     } finally {
       if (ownedTemporaryFile) {
         try {
@@ -269,8 +352,15 @@ export async function convertPastedImagesToAttachments(input: {
           if (file.exists) {
             file.delete();
           }
-        } catch (error) {
-          console.warn("Failed to remove temporary pasted image", uri, error);
+        } catch (cause) {
+          console.warn(
+            "[composer-images] failed to remove temporary pasted image",
+            new ComposerImageOperationError({
+              operation: "remove-pasted-image",
+              ...describeComposerImageUri(uri),
+              cause,
+            }),
+          );
         }
       }
     }
diff --git a/apps/mobile/src/state/thread-outbox-model.ts b/apps/mobile/src/state/thread-outbox-model.ts
index aa7a1055136..a35f29a2994 100644
--- a/apps/mobile/src/state/thread-outbox-model.ts
+++ b/apps/mobile/src/state/thread-outbox-model.ts
@@ -1,4 +1,5 @@
 import { isTransportConnectionErrorMessage } from "@t3tools/client-runtime/errors";
+import { isEnvironmentRpcUnavailableError } from "@t3tools/client-runtime/rpc";
 import type { EnvironmentShellStatus } from "@t3tools/client-runtime/state/shell";
 import { CommandId, EnvironmentId, IsoDateTime, MessageId, ThreadId } from "@t3tools/contracts";
 import * as Schema from "effect/Schema";
@@ -109,6 +110,9 @@ function errorMessage(error: unknown): string | null {
 }
 
 export function shouldRetryThreadOutboxDelivery(error: unknown): boolean {
+  if (isEnvironmentRpcUnavailableError(error)) {
+    return true;
+  }
   if (
     typeof error === "object" &&
     error !== null &&
diff --git a/apps/mobile/src/state/thread-outbox.test.ts b/apps/mobile/src/state/thread-outbox.test.ts
index d6b91c1c4f6..6609b1c3a13 100644
--- a/apps/mobile/src/state/thread-outbox.test.ts
+++ b/apps/mobile/src/state/thread-outbox.test.ts
@@ -1,4 +1,5 @@
 import { describe, expect, it } from "@effect/vitest";
+import { EnvironmentRpcUnavailableError } from "@t3tools/client-runtime/rpc";
 import { CommandId, EnvironmentId, MessageId, ThreadId } from "@t3tools/contracts";
 import { AtomRegistry } from "effect/unstable/reactivity";
 
@@ -262,6 +263,15 @@ describe("thread outbox", () => {
   });
 
   it("retries transport failures but drops deterministic command failures", () => {
+    expect(
+      shouldRetryThreadOutboxDelivery(
+        new EnvironmentRpcUnavailableError({
+          environmentId: EnvironmentId.make("environment-1"),
+          environmentLabel: "Test environment",
+          method: "thread.turn.start",
+        }),
+      ),
+    ).toBe(true);
     expect(shouldRetryThreadOutboxDelivery(new Error("Socket is not connected"))).toBe(true);
     expect(
       shouldRetryThreadOutboxDelivery({
diff --git a/apps/server/src/auth/EnvironmentAuth.test.ts b/apps/server/src/auth/EnvironmentAuth.test.ts
index 335e0685197..ae90389d38f 100644
--- a/apps/server/src/auth/EnvironmentAuth.test.ts
+++ b/apps/server/src/auth/EnvironmentAuth.test.ts
@@ -114,6 +114,16 @@ it.layer(NodeServices.layer)("EnvironmentAuth.layer", (it) => {
         .pipe(Effect.flip);
 
       expect(error._tag).toBe("ServerAuthScopeNotGrantedError");
+      if (error._tag === "ServerAuthScopeNotGrantedError") {
+        expect(error.requestedScopes).toEqual(["orchestration:read", "access:write"]);
+        expect(error.grantedScopes).toEqual([
+          "orchestration:read",
+          "orchestration:operate",
+          "terminal:operate",
+          "review:write",
+          "relay:read",
+        ]);
+      }
     }).pipe(Effect.provide(makeEnvironmentAuthLayer())),
   );
 
@@ -252,4 +262,20 @@ it.layer(NodeServices.layer)("EnvironmentAuth.layer", (it) => {
         ),
       ),
   );
+
+  it.effect("retains both session ids when rejecting self-revocation", () =>
+    Effect.gen(function* () {
+      const serverAuth = yield* EnvironmentAuth.EnvironmentAuth;
+      const issued = yield* serverAuth.issueSession();
+      const error = yield* serverAuth
+        .revokeClientSession(issued.sessionId, issued.sessionId)
+        .pipe(Effect.flip);
+
+      expect(error._tag).toBe("ServerAuthForbiddenOperationError");
+      if (error._tag === "ServerAuthForbiddenOperationError") {
+        expect(error.currentSessionId).toBe(issued.sessionId);
+        expect(error.targetSessionId).toBe(issued.sessionId);
+      }
+    }).pipe(Effect.provide(makeEnvironmentAuthLayer())),
+  );
 });
diff --git a/apps/server/src/auth/EnvironmentAuth.ts b/apps/server/src/auth/EnvironmentAuth.ts
index dd53a83ca95..fdc228a10a3 100644
--- a/apps/server/src/auth/EnvironmentAuth.ts
+++ b/apps/server/src/auth/EnvironmentAuth.ts
@@ -85,44 +85,50 @@ export class ServerAuthBootstrapCredentialValidationError extends Schema.TaggedE
 export class ServerAuthSessionCredentialValidationError extends Schema.TaggedErrorClass<ServerAuthSessionCredentialValidationError>()(
   "ServerAuthSessionCredentialValidationError",
   {
+    credentialKind: Schema.Literals(["session", "websocket-ticket"]),
     ...serverAuthInternalErrorContext,
   },
 ) {
   override get message(): string {
-    return "Failed to validate session credential.";
+    return `Failed to validate ${this.credentialKind} credential.`;
   }
 }
 
 export class ServerAuthAuthenticatedSessionIssueError extends Schema.TaggedErrorClass<ServerAuthAuthenticatedSessionIssueError>()(
   "ServerAuthAuthenticatedSessionIssueError",
   {
+    subject: Schema.String,
     ...serverAuthInternalErrorContext,
   },
 ) {
   override get message(): string {
-    return "Failed to issue authenticated session.";
+    return `Failed to issue authenticated session for ${this.subject}.`;
   }
 }
 
 export class ServerAuthAuthenticatedAccessTokenIssueError extends Schema.TaggedErrorClass<ServerAuthAuthenticatedAccessTokenIssueError>()(
   "ServerAuthAuthenticatedAccessTokenIssueError",
   {
+    subject: Schema.String,
+    scopes: Schema.Array(Schema.String),
     ...serverAuthInternalErrorContext,
   },
 ) {
   override get message(): string {
-    return "Failed to issue authenticated access token.";
+    return `Failed to issue authenticated access token for ${this.subject} with scopes [${this.scopes.join(", ")}].`;
   }
 }
 
 export class ServerAuthPairingLinkCreationError extends Schema.TaggedErrorClass<ServerAuthPairingLinkCreationError>()(
   "ServerAuthPairingLinkCreationError",
   {
+    subject: Schema.String,
+    scopes: Schema.Array(Schema.String),
     ...serverAuthInternalErrorContext,
   },
 ) {
   override get message(): string {
-    return "Failed to create pairing link.";
+    return `Failed to create pairing link for ${this.subject} with scopes [${this.scopes.join(", ")}].`;
   }
 }
 
@@ -140,22 +146,25 @@ export class ServerAuthPairingLinksListError extends Schema.TaggedErrorClass<Ser
 export class ServerAuthPairingLinkRevocationError extends Schema.TaggedErrorClass<ServerAuthPairingLinkRevocationError>()(
   "ServerAuthPairingLinkRevocationError",
   {
+    pairingLinkId: Schema.String,
     ...serverAuthInternalErrorContext,
   },
 ) {
   override get message(): string {
-    return "Failed to revoke pairing link.";
+    return `Failed to revoke pairing link ${this.pairingLinkId}.`;
   }
 }
 
 export class ServerAuthSessionTokenIssueError extends Schema.TaggedErrorClass<ServerAuthSessionTokenIssueError>()(
   "ServerAuthSessionTokenIssueError",
   {
+    subject: Schema.String,
+    scopes: Schema.Array(Schema.String),
     ...serverAuthInternalErrorContext,
   },
 ) {
   override get message(): string {
-    return "Failed to issue session token.";
+    return `Failed to issue session token for ${this.subject} with scopes [${this.scopes.join(", ")}].`;
   }
 }
 
@@ -173,55 +182,63 @@ export class ServerAuthSessionsListError extends Schema.TaggedErrorClass<ServerA
 export class ServerAuthSessionRevocationError extends Schema.TaggedErrorClass<ServerAuthSessionRevocationError>()(
   "ServerAuthSessionRevocationError",
   {
+    sessionId: Schema.String,
     ...serverAuthInternalErrorContext,
   },
 ) {
   override get message(): string {
-    return "Failed to revoke session.";
+    return `Failed to revoke session ${this.sessionId}.`;
   }
 }
 
 export class ServerAuthOtherSessionsRevocationError extends Schema.TaggedErrorClass<ServerAuthOtherSessionsRevocationError>()(
   "ServerAuthOtherSessionsRevocationError",
   {
+    excludedSessionId: Schema.String,
     ...serverAuthInternalErrorContext,
   },
 ) {
   override get message(): string {
-    return "Failed to revoke other sessions.";
+    return `Failed to revoke sessions other than ${this.excludedSessionId}.`;
   }
 }
 
 export class ServerAuthWebSocketTokenIssueError extends Schema.TaggedErrorClass<ServerAuthWebSocketTokenIssueError>()(
   "ServerAuthWebSocketTokenIssueError",
   {
+    sessionId: Schema.String,
     ...serverAuthInternalErrorContext,
   },
 ) {
   override get message(): string {
-    return "Failed to issue websocket token.";
+    return `Failed to issue websocket token for session ${this.sessionId}.`;
   }
 }
 
 export class ServerAuthDpopReplayStateRecordError extends Schema.TaggedErrorClass<ServerAuthDpopReplayStateRecordError>()(
   "ServerAuthDpopReplayStateRecordError",
   {
+    proofKeyThumbprint: Schema.String,
+    proofId: Schema.String,
+    replayKey: Schema.String,
     ...serverAuthInternalErrorContext,
   },
 ) {
   override get message(): string {
-    return "Failed to record DPoP proof replay state.";
+    return `Failed to record replay state for DPoP proof ${this.proofId} (${this.proofKeyThumbprint}).`;
   }
 }
 
 export class ServerAuthDpopReplayKeyCalculationError extends Schema.TaggedErrorClass<ServerAuthDpopReplayKeyCalculationError>()(
   "ServerAuthDpopReplayKeyCalculationError",
   {
+    proofKeyThumbprint: Schema.String,
+    proofId: Schema.String,
     ...serverAuthInternalErrorContext,
   },
 ) {
   override get message(): string {
-    return "Failed to calculate DPoP replay key.";
+    return `Failed to calculate replay key for DPoP proof ${this.proofId} (${this.proofKeyThumbprint}).`;
   }
 }
 
@@ -360,11 +377,6 @@ export const ServerAuthCredentialError = Schema.Union([
   ServerAuthInvalidCredentialError,
 ]);
 export type ServerAuthCredentialError = typeof ServerAuthCredentialError.Type;
-export const isServerAuthCredentialError = Schema.is(ServerAuthCredentialError);
-export const serverAuthCredentialReason = (
-  error: ServerAuthCredentialError,
-): "missing_credential" | "invalid_credential" =>
-  error._tag === "ServerAuthMissingCredentialError" ? "missing_credential" : "invalid_credential";
 
 export class ServerAuthInvalidScopeError extends Schema.TaggedErrorClass<ServerAuthInvalidScopeError>()(
   "ServerAuthInvalidScopeError",
@@ -377,10 +389,13 @@ export class ServerAuthInvalidScopeError extends Schema.TaggedErrorClass<ServerA
 
 export class ServerAuthScopeNotGrantedError extends Schema.TaggedErrorClass<ServerAuthScopeNotGrantedError>()(
   "ServerAuthScopeNotGrantedError",
-  {},
+  {
+    requestedScopes: Schema.Array(Schema.String),
+    grantedScopes: Schema.Array(Schema.String),
+  },
 ) {
   override get message(): string {
-    return "The requested authentication scope was not granted.";
+    return `Requested scopes [${this.requestedScopes.join(", ")}] exceed granted scopes [${this.grantedScopes.join(", ")}].`;
   }
 }
 
@@ -389,28 +404,35 @@ export const ServerAuthInvalidRequestError = Schema.Union([
   ServerAuthScopeNotGrantedError,
 ]);
 export type ServerAuthInvalidRequestError = typeof ServerAuthInvalidRequestError.Type;
-export const isServerAuthInvalidRequestError = Schema.is(ServerAuthInvalidRequestError);
-export const serverAuthInvalidRequestReason = (
-  error: ServerAuthInvalidRequestError,
-): "invalid_scope" | "scope_not_granted" =>
-  error._tag === "ServerAuthInvalidScopeError" ? "invalid_scope" : "scope_not_granted";
 
 export class ServerAuthForbiddenOperationError extends Schema.TaggedErrorClass<ServerAuthForbiddenOperationError>()(
   "ServerAuthForbiddenOperationError",
-  {},
+  {
+    currentSessionId: Schema.String,
+    targetSessionId: Schema.String,
+  },
 ) {
   override get message(): string {
-    return "The current authentication session cannot revoke itself.";
+    return `Authentication session ${this.currentSessionId} cannot revoke itself.`;
   }
 }
 
+export type ServerAuthAuthenticationInternalError =
+  | ServerAuthSessionCredentialValidationError
+  | ServerAuthDpopReplayStateRecordError
+  | ServerAuthDpopReplayKeyCalculationError;
+
+export type ServerAuthAuthenticationError =
+  | ServerAuthCredentialError
+  | ServerAuthAuthenticationInternalError;
+
 export class EnvironmentAuth extends Context.Service<
   EnvironmentAuth,
   {
     readonly getDescriptor: () => Effect.Effect<ServerAuthDescriptor>;
     readonly getSessionState: (
       request: HttpServerRequest.HttpServerRequest,
-    ) => Effect.Effect<AuthSessionState, ServerAuthInternalError>;
+    ) => Effect.Effect<AuthSessionState, ServerAuthAuthenticationInternalError>;
     readonly createBrowserSession: (
       credential: string,
       requestMetadata: AuthClientMetadata,
@@ -419,7 +441,9 @@ export class EnvironmentAuth extends Context.Service<
         readonly response: AuthBrowserSessionResult;
         readonly sessionToken: string;
       },
-      ServerAuthInvalidCredentialError | ServerAuthInternalError
+      | ServerAuthInvalidCredentialError
+      | ServerAuthBootstrapCredentialValidationError
+      | ServerAuthAuthenticatedSessionIssueError
     >;
     readonly exchangeBootstrapCredentialForAccessToken: (
       credential: string,
@@ -430,7 +454,10 @@ export class EnvironmentAuth extends Context.Service<
       },
     ) => Effect.Effect<
       AuthAccessTokenResult,
-      ServerAuthInvalidCredentialError | ServerAuthInvalidRequestError | ServerAuthInternalError
+      | ServerAuthInvalidCredentialError
+      | ServerAuthScopeNotGrantedError
+      | ServerAuthBootstrapCredentialValidationError
+      | ServerAuthAuthenticatedAccessTokenIssueError
     >;
     readonly createPairingLink: (input?: {
       readonly ttl?: Duration.Duration;
@@ -438,56 +465,61 @@ export class EnvironmentAuth extends Context.Service<
       readonly scopes?: ReadonlyArray<AuthEnvironmentScope>;
       readonly subject?: string;
       readonly proofKeyThumbprint?: string;
-    }) => Effect.Effect<IssuedPairingLink, ServerAuthInternalError>;
+    }) => Effect.Effect<IssuedPairingLink, ServerAuthPairingLinkCreationError>;
     readonly issuePairingCredential: (
       input?: AuthCreatePairingCredentialInput,
-    ) => Effect.Effect<AuthPairingCredentialResult, ServerAuthInternalError>;
+    ) => Effect.Effect<AuthPairingCredentialResult, ServerAuthPairingLinkCreationError>;
     readonly issueStartupPairingCredential: () => Effect.Effect<
       AuthPairingCredentialResult,
-      ServerAuthInternalError
+      ServerAuthPairingLinkCreationError
     >;
     readonly listPairingLinks: (input?: {
       readonly excludeSubjects?: ReadonlyArray<string>;
-    }) => Effect.Effect<ReadonlyArray<AuthPairingLink>, ServerAuthInternalError>;
-    readonly revokePairingLink: (id: string) => Effect.Effect<boolean, ServerAuthInternalError>;
+    }) => Effect.Effect<ReadonlyArray<AuthPairingLink>, ServerAuthPairingLinksListError>;
+    readonly revokePairingLink: (
+      id: string,
+    ) => Effect.Effect<boolean, ServerAuthPairingLinkRevocationError>;
     readonly issueSession: (input?: {
       readonly ttl?: Duration.Duration;
       readonly subject?: string;
       readonly scopes?: ReadonlyArray<AuthEnvironmentScope>;
       readonly label?: string;
-    }) => Effect.Effect<IssuedBearerSession, ServerAuthInternalError>;
+    }) => Effect.Effect<IssuedBearerSession, ServerAuthSessionTokenIssueError>;
     readonly listSessions: () => Effect.Effect<
       ReadonlyArray<AuthClientSession>,
-      ServerAuthInternalError
+      ServerAuthSessionsListError
     >;
     readonly revokeSession: (
       sessionId: AuthSessionId,
-    ) => Effect.Effect<boolean, ServerAuthInternalError>;
+    ) => Effect.Effect<boolean, ServerAuthSessionRevocationError>;
     readonly revokeOtherSessionsExcept: (
       sessionId: AuthSessionId,
-    ) => Effect.Effect<number, ServerAuthInternalError>;
+    ) => Effect.Effect<number, ServerAuthOtherSessionsRevocationError>;
     readonly listClientSessions: (
       currentSessionId: AuthSessionId,
-    ) => Effect.Effect<ReadonlyArray<AuthClientSession>, ServerAuthInternalError>;
+    ) => Effect.Effect<ReadonlyArray<AuthClientSession>, ServerAuthSessionsListError>;
     readonly revokeClientSession: (
       currentSessionId: AuthSessionId,
       targetSessionId: AuthSessionId,
-    ) => Effect.Effect<boolean, ServerAuthForbiddenOperationError | ServerAuthInternalError>;
+    ) => Effect.Effect<
+      boolean,
+      ServerAuthForbiddenOperationError | ServerAuthSessionRevocationError
+    >;
     readonly revokeOtherClientSessions: (
       currentSessionId: AuthSessionId,
-    ) => Effect.Effect<number, ServerAuthInternalError>;
+    ) => Effect.Effect<number, ServerAuthOtherSessionsRevocationError>;
     readonly authenticateHttpRequest: (
       request: HttpServerRequest.HttpServerRequest,
-    ) => Effect.Effect<AuthenticatedSession, ServerAuthCredentialError | ServerAuthInternalError>;
+    ) => Effect.Effect<AuthenticatedSession, ServerAuthAuthenticationError>;
     readonly authenticateWebSocketUpgrade: (
       request: HttpServerRequest.HttpServerRequest,
-    ) => Effect.Effect<AuthenticatedSession, ServerAuthCredentialError | ServerAuthInternalError>;
+    ) => Effect.Effect<AuthenticatedSession, ServerAuthAuthenticationError>;
     readonly issueWebSocketTicket: (
       session: Pick<AuthenticatedSession, "sessionId">,
-    ) => Effect.Effect<AuthWebSocketTicketResult, ServerAuthInternalError>;
+    ) => Effect.Effect<AuthWebSocketTicketResult, ServerAuthWebSocketTokenIssueError>;
     readonly issueStartupPairingUrl: (
       baseUrl: string,
-    ) => Effect.Effect<string, ServerAuthInternalError>;
+    ) => Effect.Effect<string, ServerAuthPairingLinkCreationError>;
   }
 >()("t3/auth/EnvironmentAuth") {}
 
@@ -514,7 +546,7 @@ const bySessionPriority = (left: AuthClientSession, right: AuthClientSession) =>
 
 export function toBootstrapExchangeError(
   cause: PairingGrantStore.BootstrapCredentialError,
-): ServerAuthInvalidCredentialError | ServerAuthInternalError {
+): ServerAuthInvalidCredentialError | ServerAuthBootstrapCredentialValidationError {
   if (PairingGrantStore.isBootstrapCredentialInternalError(cause)) {
     return new ServerAuthBootstrapCredentialValidationError({ cause });
   }
@@ -526,12 +558,17 @@ export function toBootstrapExchangeError(
 
 const mapSessionVerificationErrors = <A, R>(
   effect: Effect.Effect<A, SessionStore.SessionCredentialError, R>,
-): Effect.Effect<A, ServerAuthInvalidCredentialError | ServerAuthInternalError, R> =>
+  credentialKind: ServerAuthSessionCredentialValidationError["credentialKind"],
+): Effect.Effect<
+  A,
+  ServerAuthInvalidCredentialError | ServerAuthSessionCredentialValidationError,
+  R
+> =>
   effect.pipe(
     Effect.mapError((cause) =>
       SessionStore.isSessionCredentialInvalidError(cause)
         ? new ServerAuthInvalidCredentialError({ cause })
-        : new ServerAuthSessionCredentialValidationError({ cause }),
+        : new ServerAuthSessionCredentialValidationError({ credentialKind, cause }),
     ),
   );
 
@@ -565,7 +602,7 @@ export const make = Effect.gen(function* () {
     token: string,
   ): Effect.Effect<
     AuthenticatedSession,
-    ServerAuthInvalidCredentialError | ServerAuthInternalError
+    ServerAuthInvalidCredentialError | ServerAuthSessionCredentialValidationError
   > =>
     sessions.verify(token).pipe(
       Effect.tapError((cause) =>
@@ -585,12 +622,12 @@ export const make = Effect.gen(function* () {
         ...(session.proofKeyThumbprint ? { proofKeyThumbprint: session.proofKeyThumbprint } : {}),
         ...(session.expiresAt ? { expiresAt: session.expiresAt } : {}),
       })),
-      mapSessionVerificationErrors,
+      (effect) => mapSessionVerificationErrors(effect, "session"),
     );
 
   const authenticateRequest = (
     request: HttpServerRequest.HttpServerRequest,
-  ): Effect.Effect<AuthenticatedSession, ServerAuthCredentialError | ServerAuthInternalError> => {
+  ): Effect.Effect<AuthenticatedSession, ServerAuthAuthenticationError> => {
     const cookieToken = request.cookies[sessions.cookieName];
     const bearerToken = parseBearerToken(request);
     const dpopToken = parseDpopToken(request);
@@ -642,12 +679,18 @@ export const make = Effect.gen(function* () {
             ...(session.expiresAt ? { expiresAt: DateTime.toUtc(session.expiresAt) } : {}),
           }) satisfies AuthSessionState,
       ),
-      Effect.catchIf(isServerAuthCredentialError, () =>
-        Effect.succeed({
-          authenticated: false,
-          auth: descriptor,
-        } satisfies AuthSessionState),
-      ),
+      Effect.catchTags({
+        ServerAuthMissingCredentialError: () =>
+          Effect.succeed({
+            authenticated: false,
+            auth: descriptor,
+          } satisfies AuthSessionState),
+        ServerAuthInvalidCredentialError: () =>
+          Effect.succeed({
+            authenticated: false,
+            auth: descriptor,
+          } satisfies AuthSessionState),
+      }),
       Effect.withSpan("EnvironmentAuth.getSessionState"),
     );
 
@@ -669,7 +712,13 @@ export const make = Effect.gen(function* () {
             },
           })
           .pipe(
-            Effect.mapError((cause) => new ServerAuthAuthenticatedSessionIssueError({ cause })),
+            Effect.mapError(
+              (cause) =>
+                new ServerAuthAuthenticatedSessionIssueError({
+                  subject: grant.subject,
+                  cause,
+                }),
+            ),
           ),
       ),
       Effect.map(
@@ -695,7 +744,10 @@ export const make = Effect.gen(function* () {
           Effect.gen(function* () {
             const grantedScopes = requestedScopes ?? grant.scopes;
             if (!grantedScopes.every((scope) => grant.scopes.includes(scope))) {
-              return yield* new ServerAuthScopeNotGrantedError({});
+              return yield* new ServerAuthScopeNotGrantedError({
+                requestedScopes: grantedScopes,
+                grantedScopes: grant.scopes,
+              });
             }
             return yield* sessions
               .issue({
@@ -715,7 +767,12 @@ export const make = Effect.gen(function* () {
               })
               .pipe(
                 Effect.mapError(
-                  (cause) => new ServerAuthAuthenticatedAccessTokenIssueError({ cause }),
+                  (cause) =>
+                    new ServerAuthAuthenticatedAccessTokenIssueError({
+                      subject: grant.subject,
+                      scopes: grantedScopes,
+                      cause,
+                    }),
                 ),
               );
           }),
@@ -765,28 +822,33 @@ export const make = Effect.gen(function* () {
 
   const createPairingLink: EnvironmentAuth["Service"]["createPairingLink"] = Effect.fn(
     "EnvironmentAuth.createPairingLink",
-  )(
-    function* (input) {
-      const createdAt = yield* DateTime.now;
-      const issued = yield* bootstrapCredentials.issueOneTimeToken({
-        scopes: input?.scopes ?? AuthStandardClientScopes,
-        subject: input?.subject ?? "one-time-token",
+  )(function* (input) {
+    const scopes = input?.scopes ?? AuthStandardClientScopes;
+    const subject = input?.subject ?? "one-time-token";
+    const createdAt = yield* DateTime.now;
+    const issued = yield* bootstrapCredentials
+      .issueOneTimeToken({
+        scopes,
+        subject,
         ...(input?.ttl ? { ttl: input.ttl } : {}),
         ...(input?.label ? { label: input.label } : {}),
         ...(input?.proofKeyThumbprint ? { proofKeyThumbprint: input.proofKeyThumbprint } : {}),
-      });
-      return {
-        id: issued.id,
-        credential: issued.credential,
-        scopes: input?.scopes ?? AuthStandardClientScopes,
-        subject: input?.subject ?? "one-time-token",
-        ...(issued.label ? { label: issued.label } : {}),
-        createdAt: DateTime.toUtc(createdAt),
-        expiresAt: DateTime.toUtc(issued.expiresAt),
-      } satisfies IssuedPairingLink;
-    },
-    Effect.mapError((cause) => new ServerAuthPairingLinkCreationError({ cause })),
-  );
+      })
+      .pipe(
+        Effect.mapError(
+          (cause) => new ServerAuthPairingLinkCreationError({ subject, scopes, cause }),
+        ),
+      );
+    return {
+      id: issued.id,
+      credential: issued.credential,
+      scopes,
+      subject,
+      ...(issued.label ? { label: issued.label } : {}),
+      createdAt: DateTime.toUtc(createdAt),
+      expiresAt: DateTime.toUtc(issued.expiresAt),
+    } satisfies IssuedPairingLink;
+  });
 
   const listPairingLinks: EnvironmentAuth["Service"]["listPairingLinks"] = (input) =>
     bootstrapCredentials.listActive().pipe(
@@ -806,16 +868,20 @@ export const make = Effect.gen(function* () {
 
   const revokePairingLink: EnvironmentAuth["Service"]["revokePairingLink"] = (id) =>
     bootstrapCredentials.revoke(id).pipe(
-      Effect.mapError((cause) => new ServerAuthPairingLinkRevocationError({ cause })),
+      Effect.mapError(
+        (cause) => new ServerAuthPairingLinkRevocationError({ pairingLinkId: id, cause }),
+      ),
       Effect.withSpan("EnvironmentAuth.revokePairingLink"),
     );
 
-  const issueSession: EnvironmentAuth["Service"]["issueSession"] = (input) =>
-    sessions
+  const issueSession: EnvironmentAuth["Service"]["issueSession"] = (input) => {
+    const subject = input?.subject ?? DEFAULT_SESSION_SUBJECT;
+    const scopes = input?.scopes ?? AuthAdministrativeScopes;
+    return sessions
       .issue({
-        subject: input?.subject ?? DEFAULT_SESSION_SUBJECT,
+        subject,
         method: "bearer-access-token",
-        scopes: input?.scopes ?? AuthAdministrativeScopes,
+        scopes,
         client: {
           ...(input?.label ? { label: input.label } : {}),
           deviceType: "bot",
@@ -830,14 +896,17 @@ export const make = Effect.gen(function* () {
               token: issued.token,
               method: "bearer-access-token",
               scopes: issued.scopes,
-              subject: input?.subject ?? DEFAULT_SESSION_SUBJECT,
+              subject,
               client: issued.client,
               expiresAt: DateTime.toUtc(issued.expiresAt),
             }) satisfies IssuedBearerSession,
         ),
-        Effect.mapError((cause) => new ServerAuthSessionTokenIssueError({ cause })),
+        Effect.mapError(
+          (cause) => new ServerAuthSessionTokenIssueError({ subject, scopes, cause }),
+        ),
         Effect.withSpan("EnvironmentAuth.issueSession"),
       );
+  };
 
   const listSessions: EnvironmentAuth["Service"]["listSessions"] = () =>
     sessions.listActive().pipe(
@@ -848,7 +917,7 @@ export const make = Effect.gen(function* () {
 
   const revokeSession: EnvironmentAuth["Service"]["revokeSession"] = (sessionId) =>
     sessions.revoke(sessionId).pipe(
-      Effect.mapError((cause) => new ServerAuthSessionRevocationError({ cause })),
+      Effect.mapError((cause) => new ServerAuthSessionRevocationError({ sessionId, cause })),
       Effect.withSpan("EnvironmentAuth.revokeSession"),
     );
 
@@ -856,7 +925,10 @@ export const make = Effect.gen(function* () {
     sessionId,
   ) =>
     sessions.revokeAllExcept(sessionId).pipe(
-      Effect.mapError((cause) => new ServerAuthOtherSessionsRevocationError({ cause })),
+      Effect.mapError(
+        (cause) =>
+          new ServerAuthOtherSessionsRevocationError({ excludedSessionId: sessionId, cause }),
+      ),
       Effect.withSpan("EnvironmentAuth.revokeOtherSessionsExcept"),
     );
 
@@ -891,7 +963,10 @@ export const make = Effect.gen(function* () {
     "EnvironmentAuth.revokeClientSession",
   )(function* (currentSessionId, targetSessionId) {
     if (currentSessionId === targetSessionId) {
-      return yield* new ServerAuthForbiddenOperationError({});
+      return yield* new ServerAuthForbiddenOperationError({
+        currentSessionId,
+        targetSessionId,
+      });
     }
     return yield* revokeSession(targetSessionId);
   });
@@ -917,7 +992,9 @@ export const make = Effect.gen(function* () {
 
   const issueWebSocketTicket: EnvironmentAuth["Service"]["issueWebSocketTicket"] = (session) =>
     sessions.issueWebSocketToken(session.sessionId).pipe(
-      Effect.mapError((cause) => new ServerAuthWebSocketTokenIssueError({ cause })),
+      Effect.mapError(
+        (cause) => new ServerAuthWebSocketTokenIssueError({ sessionId: session.sessionId, cause }),
+      ),
       Effect.map(
         (issued) =>
           ({
@@ -947,7 +1024,7 @@ export const make = Effect.gen(function* () {
               scopes: session.scopes,
               ...(session.expiresAt ? { expiresAt: session.expiresAt } : {}),
             })),
-            mapSessionVerificationErrors,
+            (effect) => mapSessionVerificationErrors(effect, "websocket-ticket"),
           );
         }
       }
diff --git a/apps/server/src/auth/ServerSecretStore.test.ts b/apps/server/src/auth/ServerSecretStore.test.ts
index d4411fb9f3b..824a7888617 100644
--- a/apps/server/src/auth/ServerSecretStore.test.ts
+++ b/apps/server/src/auth/ServerSecretStore.test.ts
@@ -45,6 +45,31 @@ const makePermissionDeniedSecretStoreLayer = () =>
     Layer.provideMerge(PermissionDeniedFileSystemLayer),
   );
 
+const DirectoryCreateFailureFileSystemLayer = Layer.effect(
+  FileSystem.FileSystem,
+  Effect.gen(function* () {
+    const fileSystem = yield* FileSystem.FileSystem;
+    return {
+      ...fileSystem,
+      makeDirectory: (path) =>
+        Effect.fail(
+          PlatformError.systemError({
+            _tag: "PermissionDenied",
+            module: "FileSystem",
+            method: "makeDirectory",
+            pathOrDescriptor: String(path),
+          }),
+        ),
+    } satisfies FileSystem.FileSystem;
+  }),
+).pipe(Layer.provide(NodeServices.layer));
+
+const makeDirectoryCreateFailureSecretStoreLayer = (config: ServerConfig.ServerConfig["Service"]) =>
+  ServerSecretStore.layer.pipe(
+    Layer.provide(Layer.succeed(ServerConfig.ServerConfig, config)),
+    Layer.provideMerge(DirectoryCreateFailureFileSystemLayer),
+  );
+
 const RenameFailureFileSystemLayer = Layer.effect(
   FileSystem.FileSystem,
   Effect.gen(function* () {
@@ -145,7 +170,56 @@ const makeConcurrentCreateSecretStoreLayer = () =>
     Layer.provideMerge(ConcurrentReadMissFileSystemLayer),
   );
 
+const ConcurrentCreationWithoutReadableSecretFileSystemLayer = Layer.effect(
+  FileSystem.FileSystem,
+  Effect.gen(function* () {
+    const fileSystem = yield* FileSystem.FileSystem;
+
+    return {
+      ...fileSystem,
+      readFile: (path) =>
+        Effect.fail(
+          PlatformError.systemError({
+            _tag: "NotFound",
+            module: "FileSystem",
+            method: "readFile",
+            pathOrDescriptor: path,
+          }),
+        ),
+      open: (path) =>
+        Effect.fail(
+          PlatformError.systemError({
+            _tag: "AlreadyExists",
+            module: "FileSystem",
+            method: "open",
+            pathOrDescriptor: path,
+          }),
+        ),
+    } satisfies FileSystem.FileSystem;
+  }),
+).pipe(Layer.provide(NodeServices.layer));
+
+const makeConcurrentCreationWithoutReadableSecretStoreLayer = () =>
+  ServerSecretStore.layer.pipe(
+    Layer.provide(makeServerConfigLayer()),
+    Layer.provideMerge(ConcurrentCreationWithoutReadableSecretFileSystemLayer),
+  );
+
 it.layer(NodeServices.layer)("ServerSecretStore.layer", (it) => {
+  it.effect("preserves directory context when secret-store initialization fails", () =>
+    Effect.gen(function* () {
+      const config = yield* ServerConfig.ServerConfig.pipe(Effect.provide(makeServerConfigLayer()));
+      const error = yield* Layer.build(makeDirectoryCreateFailureSecretStoreLayer(config)).pipe(
+        Effect.scoped,
+        Effect.flip,
+      );
+
+      assert.instanceOf(error, ServerSecretStore.SecretStoreDirectoryCreateError);
+      assert.match(error.directoryPath, /secrets$/u);
+      assert.instanceOf(error.cause, PlatformError.PlatformError);
+    }),
+  );
+
   it.effect("returns Option.none when a secret file does not exist", () =>
     Effect.gen(function* () {
       const secretStore = yield* ServerSecretStore.ServerSecretStore;
@@ -186,6 +260,25 @@ it.layer(NodeServices.layer)("ServerSecretStore.layer", (it) => {
     }).pipe(Effect.provide(makeConcurrentCreateSecretStoreLayer())),
   );
 
+  it.effect("preserves the persist failure when a concurrent secret remains unreadable", () =>
+    Effect.gen(function* () {
+      const secretStore = yield* ServerSecretStore.ServerSecretStore;
+
+      const error = yield* Effect.flip(secretStore.getOrCreateRandom("session-signing-key", 32));
+
+      assert.instanceOf(error, ServerSecretStore.SecretStoreConcurrentReadError);
+      assert.equal(error.secretName, "session-signing-key");
+      assert.equal(
+        error.message,
+        "Failed to read secret session-signing-key after concurrent creation.",
+      );
+      assert.instanceOf(error.cause, ServerSecretStore.SecretStorePersistError);
+      assert.equal(error.cause.operation, "create");
+      assert.instanceOf(error.cause.cause, PlatformError.PlatformError);
+      assert.equal(error.cause.cause.reason._tag, "AlreadyExists");
+    }).pipe(Effect.provide(makeConcurrentCreationWithoutReadableSecretStoreLayer())),
+  );
+
   it.effect("uses restrictive permissions for the secret directory and files", () =>
     Effect.gen(function* () {
       const chmodCalls: Array<{ readonly path: string; readonly mode: number }> = [];
@@ -232,7 +325,8 @@ it.layer(NodeServices.layer)("ServerSecretStore.layer", (it) => {
       const error = yield* Effect.flip(secretStore.getOrCreateRandom("session-signing-key", 32));
 
       assert.instanceOf(error, ServerSecretStore.SecretStoreReadError);
-      assert.include(error.message, "Failed to read secret session-signing-key.");
+      assert.equal(error.secretName, "session-signing-key");
+      assert.match(error.secretPath, /session-signing-key\.bin$/u);
       assert.instanceOf(error.cause, PlatformError.PlatformError);
       assert.equal((error.cause as PlatformError.PlatformError).reason._tag, "PermissionDenied");
     }).pipe(Effect.provide(makePermissionDeniedSecretStoreLayer())),
@@ -247,7 +341,9 @@ it.layer(NodeServices.layer)("ServerSecretStore.layer", (it) => {
       );
 
       assert.instanceOf(error, ServerSecretStore.SecretStorePersistError);
-      assert.include(error.message, "Failed to persist secret session-signing-key.");
+      assert.equal(error.operation, "set");
+      assert.equal(error.secretName, "session-signing-key");
+      assert.match(error.secretPath, /session-signing-key\.bin$/u);
       assert.instanceOf(error.cause, PlatformError.PlatformError);
       assert.equal((error.cause as PlatformError.PlatformError).reason._tag, "PermissionDenied");
     }).pipe(Effect.provide(makeRenameFailureSecretStoreLayer())),
@@ -260,7 +356,8 @@ it.layer(NodeServices.layer)("ServerSecretStore.layer", (it) => {
       const error = yield* Effect.flip(secretStore.remove("session-signing-key"));
 
       assert.instanceOf(error, ServerSecretStore.SecretStoreRemoveError);
-      assert.include(error.message, "Failed to remove secret session-signing-key.");
+      assert.equal(error.secretName, "session-signing-key");
+      assert.match(error.secretPath, /session-signing-key\.bin$/u);
       assert.instanceOf(error.cause, PlatformError.PlatformError);
       assert.equal((error.cause as PlatformError.PlatformError).reason._tag, "PermissionDenied");
     }).pipe(Effect.provide(makeRemoveFailureSecretStoreLayer())),
diff --git a/apps/server/src/auth/ServerSecretStore.ts b/apps/server/src/auth/ServerSecretStore.ts
index 5e9890c1ea2..7608d3ce577 100644
--- a/apps/server/src/auth/ServerSecretStore.ts
+++ b/apps/server/src/auth/ServerSecretStore.ts
@@ -11,114 +11,137 @@ import * as Schema from "effect/Schema";
 
 import * as ServerConfig from "../config.ts";
 
-const secretStoreErrorContext = {
-  resource: Schema.String,
+const storedSecretErrorContext = {
+  secretName: Schema.String,
+  secretPath: Schema.String,
   cause: Schema.Defect(),
 };
 
-export class SecretStoreSecureError extends Schema.TaggedErrorClass<SecretStoreSecureError>()(
-  "SecretStoreSecureError",
+export class SecretStoreDirectoryCreateError extends Schema.TaggedErrorClass<SecretStoreDirectoryCreateError>()(
+  "SecretStoreDirectoryCreateError",
   {
-    ...secretStoreErrorContext,
+    directoryPath: Schema.String,
+    cause: Schema.Defect(),
   },
 ) {
   override get message(): string {
-    return `Failed to secure ${this.resource}.`;
+    return `Failed to create secret store directory ${this.directoryPath}.`;
+  }
+}
+
+export class SecretStoreDirectorySecureError extends Schema.TaggedErrorClass<SecretStoreDirectorySecureError>()(
+  "SecretStoreDirectorySecureError",
+  {
+    directoryPath: Schema.String,
+    cause: Schema.Defect(),
+  },
+) {
+  override get message(): string {
+    return `Failed to secure secret store directory ${this.directoryPath}.`;
   }
 }
 
 export class SecretStoreReadError extends Schema.TaggedErrorClass<SecretStoreReadError>()(
   "SecretStoreReadError",
   {
-    ...secretStoreErrorContext,
+    ...storedSecretErrorContext,
   },
 ) {
   override get message(): string {
-    return `Failed to read ${this.resource}.`;
+    return `Failed to read secret ${this.secretName} at ${this.secretPath}.`;
   }
 }
 
-export class SecretStoreTemporaryPathError extends Schema.TaggedErrorClass<SecretStoreTemporaryPathError>()(
-  "SecretStoreTemporaryPathError",
+export class SecretStoreTemporaryPathGenerationError extends Schema.TaggedErrorClass<SecretStoreTemporaryPathGenerationError>()(
+  "SecretStoreTemporaryPathGenerationError",
   {
-    ...secretStoreErrorContext,
+    secretName: Schema.String,
+    secretPath: Schema.String,
+    cause: Schema.Defect(),
   },
 ) {
   override get message(): string {
-    return `Failed to create temporary path for ${this.resource}.`;
+    return `Failed to generate a temporary path for secret ${this.secretName} at ${this.secretPath}.`;
   }
 }
 
 export class SecretStorePersistError extends Schema.TaggedErrorClass<SecretStorePersistError>()(
   "SecretStorePersistError",
   {
-    ...secretStoreErrorContext,
+    operation: Schema.Literals(["create", "set"]),
+    ...storedSecretErrorContext,
   },
 ) {
   override get message(): string {
-    return `Failed to persist ${this.resource}.`;
+    return `Failed to ${this.operation} secret ${this.secretName} at ${this.secretPath}.`;
   }
 }
 
 export class SecretStoreRandomGenerationError extends Schema.TaggedErrorClass<SecretStoreRandomGenerationError>()(
   "SecretStoreRandomGenerationError",
   {
-    ...secretStoreErrorContext,
+    secretName: Schema.String,
+    byteCount: Schema.Number,
+    cause: Schema.Defect(),
   },
 ) {
   override get message(): string {
-    return `Failed to generate random bytes for ${this.resource}.`;
+    return `Failed to generate ${this.byteCount} random bytes for secret ${this.secretName}.`;
   }
 }
 
 export class SecretStoreConcurrentReadError extends Schema.TaggedErrorClass<SecretStoreConcurrentReadError>()(
   "SecretStoreConcurrentReadError",
   {
-    resource: Schema.String,
+    secretName: Schema.String,
+    cause: Schema.Defect(),
   },
 ) {
   override get message(): string {
-    return `Failed to read ${this.resource} after concurrent creation.`;
+    return `Failed to read secret ${this.secretName} after concurrent creation.`;
   }
 }
 
 export class SecretStoreRemoveError extends Schema.TaggedErrorClass<SecretStoreRemoveError>()(
   "SecretStoreRemoveError",
   {
-    ...secretStoreErrorContext,
+    ...storedSecretErrorContext,
   },
 ) {
   override get message(): string {
-    return `Failed to remove ${this.resource}.`;
+    return `Failed to remove secret ${this.secretName} at ${this.secretPath}.`;
   }
 }
 
 export class SecretStoreDecodeError extends Schema.TaggedErrorClass<SecretStoreDecodeError>()(
   "SecretStoreDecodeError",
   {
-    ...secretStoreErrorContext,
+    secretName: Schema.String,
+    cause: Schema.Defect(),
   },
 ) {
   override get message(): string {
-    return `Failed to decode ${this.resource}.`;
+    return `Failed to decode secret ${this.secretName}.`;
   }
 }
 
 export class SecretStoreEncodeError extends Schema.TaggedErrorClass<SecretStoreEncodeError>()(
   "SecretStoreEncodeError",
   {
-    ...secretStoreErrorContext,
+    secretName: Schema.String,
+    cause: Schema.Defect(),
   },
 ) {
   override get message(): string {
-    return `Failed to encode ${this.resource}.`;
+    return `Failed to encode secret ${this.secretName}.`;
   }
 }
 
 export const SecretStoreError = Schema.Union([
-  SecretStoreSecureError,
+  SecretStoreDirectoryCreateError,
+  SecretStoreDirectorySecureError,
   SecretStoreReadError,
-  SecretStoreTemporaryPathError,
+  SecretStoreTemporaryPathGenerationError,
   SecretStorePersistError,
   SecretStoreRandomGenerationError,
   SecretStoreConcurrentReadError,
@@ -138,14 +161,26 @@ export const isSecretAlreadyExistsError = (error: SecretStoreError): boolean =>
 export class ServerSecretStore extends Context.Service<
   ServerSecretStore,
   {
-    readonly get: (name: string) => Effect.Effect<Option.Option<Uint8Array>, SecretStoreError>;
-    readonly set: (name: string, value: Uint8Array) => Effect.Effect<void, SecretStoreError>;
-    readonly create: (name: string, value: Uint8Array) => Effect.Effect<void, SecretStoreError>;
+    readonly get: (name: string) => Effect.Effect<Option.Option<Uint8Array>, SecretStoreReadError>;
+    readonly set: (
+      name: string,
+      value: Uint8Array,
+    ) => Effect.Effect<void, SecretStoreTemporaryPathGenerationError | SecretStorePersistError>;
+    readonly create: (
+      name: string,
+      value: Uint8Array,
+    ) => Effect.Effect<void, SecretStorePersistError>;
     readonly getOrCreateRandom: (
       name: string,
       bytes: number,
-    ) => Effect.Effect<Uint8Array, SecretStoreError>;
-    readonly remove: (name: string) => Effect.Effect<void, SecretStoreError>;
+    ) => Effect.Effect<
+      Uint8Array,
+      | SecretStoreReadError
+      | SecretStoreRandomGenerationError
+      | SecretStorePersistError
+      | SecretStoreConcurrentReadError
+    >;
+    readonly remove: (name: string) => Effect.Effect<void, SecretStoreRemoveError>;
   }
 >()("t3/auth/ServerSecretStore") {}
 
@@ -155,12 +190,20 @@ export const make = Effect.gen(function* () {
   const path = yield* Path.Path;
   const serverConfig = yield* ServerConfig.ServerConfig;
 
-  yield* fileSystem.makeDirectory(serverConfig.secretsDir, { recursive: true });
+  yield* fileSystem.makeDirectory(serverConfig.secretsDir, { recursive: true }).pipe(
+    Effect.mapError(
+      (cause) =>
+        new SecretStoreDirectoryCreateError({
+          directoryPath: serverConfig.secretsDir,
+          cause,
+        }),
+    ),
+  );
   yield* fileSystem.chmod(serverConfig.secretsDir, 0o700).pipe(
     Effect.mapError(
       (cause) =>
-        new SecretStoreSecureError({
-          resource: `secrets directory ${serverConfig.secretsDir}`,
+        new SecretStoreDirectorySecureError({
+          directoryPath: serverConfig.secretsDir,
           cause,
         }),
     ),
@@ -168,29 +211,33 @@ export const make = Effect.gen(function* () {
 
   const resolveSecretPath = (name: string) => path.join(serverConfig.secretsDir, `${name}.bin`);
 
-  const get: ServerSecretStore["Service"]["get"] = (name) =>
-    fileSystem.readFile(resolveSecretPath(name)).pipe(
+  const get: ServerSecretStore["Service"]["get"] = (name) => {
+    const secretPath = resolveSecretPath(name);
+    return fileSystem.readFile(secretPath).pipe(
       Effect.map((bytes) => Option.some(Uint8Array.from(bytes))),
       Effect.catch((cause) =>
         cause.reason._tag === "NotFound"
           ? Effect.succeed(Option.none())
           : Effect.fail(
               new SecretStoreReadError({
-                resource: `secret ${name}`,
+                secretName: name,
+                secretPath,
                 cause,
               }),
             ),
       ),
       Effect.withSpan("ServerSecretStore.get"),
     );
+  };
 
   const set: ServerSecretStore["Service"]["set"] = (name, value) => {
     const secretPath = resolveSecretPath(name);
     return crypto.randomUUIDv4.pipe(
       Effect.mapError(
         (cause) =>
-          new SecretStoreTemporaryPathError({
-            resource: `secret ${name}`,
+          new SecretStoreTemporaryPathGenerationError({
+            secretName: name,
+            secretPath,
             cause,
           }),
       ),
@@ -208,7 +255,9 @@ export const make = Effect.gen(function* () {
               Effect.flatMap(() =>
                 Effect.fail(
                   new SecretStorePersistError({
-                    resource: `secret ${name}`,
+                    operation: "set",
+                    secretName: name,
+                    secretPath,
                     cause,
                   }),
                 ),
@@ -237,7 +286,9 @@ export const make = Effect.gen(function* () {
       Effect.mapError(
         (cause) =>
           new SecretStorePersistError({
-            resource: `secret ${name}`,
+            operation: "create",
+            secretName: name,
+            secretPath,
             cause,
           }),
       ),
@@ -254,30 +305,33 @@ export const make = Effect.gen(function* () {
               Effect.mapError(
                 (cause) =>
                   new SecretStoreRandomGenerationError({
-                    resource: `secret ${name}`,
+                    secretName: name,
+                    byteCount: bytes,
                     cause,
                   }),
               ),
               Effect.flatMap((generated) =>
                 create(name, generated).pipe(
                   Effect.as(Uint8Array.from(generated)),
-                  Effect.catchIf(isSecretStoreError, (error) =>
-                    isSecretAlreadyExistsError(error)
-                      ? get(name).pipe(
-                          Effect.flatMap(
-                            Option.match({
-                              onSome: Effect.succeed,
-                              onNone: () =>
-                                Effect.fail(
-                                  new SecretStoreConcurrentReadError({
-                                    resource: `secret ${name}`,
-                                  }),
-                                ),
-                            }),
-                          ),
-                        )
-                      : Effect.fail(error),
-                  ),
+                  Effect.catchTags({
+                    SecretStorePersistError: (error) =>
+                      isSecretAlreadyExistsError(error)
+                        ? get(name).pipe(
+                            Effect.flatMap(
+                              Option.match({
+                                onSome: Effect.succeed,
+                                onNone: () =>
+                                  Effect.fail(
+                                    new SecretStoreConcurrentReadError({
+                                      secretName: name,
+                                      cause: error,
+                                    }),
+                                  ),
+                              }),
+                            ),
+                          )
+                        : Effect.fail(error),
+                  }),
                 ),
               ),
             ),
@@ -286,20 +340,23 @@ export const make = Effect.gen(function* () {
       Effect.withSpan("ServerSecretStore.getOrCreateRandom"),
     );
 
-  const remove: ServerSecretStore["Service"]["remove"] = (name) =>
-    fileSystem.remove(resolveSecretPath(name)).pipe(
+  const remove: ServerSecretStore["Service"]["remove"] = (name) => {
+    const secretPath = resolveSecretPath(name);
+    return fileSystem.remove(secretPath).pipe(
       Effect.catch((cause) =>
         cause.reason._tag === "NotFound"
           ? Effect.void
           : Effect.fail(
               new SecretStoreRemoveError({
-                resource: `secret ${name}`,
+                secretName: name,
+                secretPath,
                 cause,
               }),
             ),
       ),
       Effect.withSpan("ServerSecretStore.remove"),
     );
+  };
 
   return ServerSecretStore.of({
     get,
diff --git a/apps/server/src/auth/dpop.test.ts b/apps/server/src/auth/dpop.test.ts
index fa75c407b0c..d01417cebfc 100644
--- a/apps/server/src/auth/dpop.test.ts
+++ b/apps/server/src/auth/dpop.test.ts
@@ -6,7 +6,9 @@ import { mapDpopReplayStoreError } from "./dpop.ts";
 
 const storeFailure = (tag: "AlreadyExists" | "PermissionDenied") =>
   new SecretStorePersistError({
-    resource: "DPoP proof",
+    operation: "create",
+    secretName: "DPoP proof",
+    secretPath: "dpop-proof.bin",
     cause: PlatformError.systemError({
       _tag: tag,
       module: "FileSystem",
@@ -15,10 +17,16 @@ const storeFailure = (tag: "AlreadyExists" | "PermissionDenied") =>
     }),
   });
 
+const replayContext = {
+  proofKeyThumbprint: "proof-key-thumbprint",
+  proofId: "proof-id",
+  replayKey: "replay-key",
+};
+
 describe("mapDpopReplayStoreError", () => {
   it("reports replay conflicts as invalid credentials", () => {
     const cause = storeFailure("AlreadyExists");
-    const error = mapDpopReplayStoreError(cause);
+    const error = mapDpopReplayStoreError(cause, replayContext);
 
     expect(error._tag).toBe("ServerAuthInvalidCredentialError");
     if (error._tag === "ServerAuthInvalidCredentialError") {
@@ -27,11 +35,18 @@ describe("mapDpopReplayStoreError", () => {
   });
 
   it("reports replay-store availability failures as internal errors", () => {
-    const error = mapDpopReplayStoreError(storeFailure("PermissionDenied"));
+    const cause = storeFailure("PermissionDenied");
+    const error = mapDpopReplayStoreError(cause, replayContext);
 
     expect(error._tag).toBe("ServerAuthDpopReplayStateRecordError");
     if (error._tag === "ServerAuthDpopReplayStateRecordError") {
-      expect(error.message).toBe("Failed to record DPoP proof replay state.");
+      expect(error.message).toBe(
+        "Failed to record replay state for DPoP proof proof-id (proof-key-thumbprint).",
+      );
+      expect(error.proofKeyThumbprint).toBe(replayContext.proofKeyThumbprint);
+      expect(error.proofId).toBe(replayContext.proofId);
+      expect(error.replayKey).toBe(replayContext.replayKey);
+      expect(error.cause).toBe(cause);
     }
   });
 });
diff --git a/apps/server/src/auth/dpop.ts b/apps/server/src/auth/dpop.ts
index 87dc0c263e2..f5da796e747 100644
--- a/apps/server/src/auth/dpop.ts
+++ b/apps/server/src/auth/dpop.ts
@@ -9,7 +9,6 @@ import {
   ServerAuthDpopReplayKeyCalculationError,
   ServerAuthDpopReplayStateRecordError,
   ServerAuthInvalidCredentialError,
-  type ServerAuthInternalError,
 } from "./EnvironmentAuth.ts";
 import * as ServerSecretStore from "./ServerSecretStore.ts";
 
@@ -31,13 +30,19 @@ export function requestAbsoluteUrl(request: HttpServerRequest.HttpServerRequest)
 
 export const mapDpopReplayStoreError = (
   error: ServerSecretStore.SecretStoreError,
-): ServerAuthInvalidCredentialError | ServerAuthInternalError =>
+  context: {
+    readonly proofKeyThumbprint: string;
+    readonly proofId: string;
+    readonly replayKey: string;
+  },
+): ServerAuthInvalidCredentialError | ServerAuthDpopReplayStateRecordError =>
   ServerSecretStore.isSecretAlreadyExistsError(error)
     ? new ServerAuthInvalidCredentialError({
         diagnostic: "DPoP proof replayed.",
         cause: error,
       })
     : new ServerAuthDpopReplayStateRecordError({
+        ...context,
         cause: error,
       });
 
@@ -71,6 +76,8 @@ export const verifyRequestDpopProof = (input: {
       Effect.mapError(
         (cause) =>
           new ServerAuthDpopReplayKeyCalculationError({
+            proofKeyThumbprint: result.thumbprint,
+            proofId: result.jti,
             cause,
           }),
       ),
@@ -88,8 +95,12 @@ export const verifyRequestDpopProof = (input: {
         ),
       )
       .pipe(
-        Effect.catchIf(ServerSecretStore.isSecretStoreError, (error) =>
-          Effect.fail(mapDpopReplayStoreError(error)),
+        Effect.mapError((error) =>
+          mapDpopReplayStoreError(error, {
+            proofKeyThumbprint: result.thumbprint,
+            proofId: result.jti,
+            replayKey,
+          }),
         ),
       );
     return result.thumbprint;
diff --git a/apps/server/src/auth/http.ts b/apps/server/src/auth/http.ts
index 71fb00b970a..03977cf9ffb 100644
--- a/apps/server/src/auth/http.ts
+++ b/apps/server/src/auth/http.ts
@@ -151,6 +151,22 @@ export function failEnvironmentInternal(reason: EnvironmentInternalErrorReason,
   });
 }
 
+const failAuthenticationInternal = (error: EnvironmentAuth.ServerAuthAuthenticationInternalError) =>
+  failEnvironmentInternal("internal_error", error);
+
+export const catchEnvironmentAuthenticationErrors = <A, R>(
+  effect: Effect.Effect<A, EnvironmentAuth.ServerAuthAuthenticationError, R>,
+) =>
+  effect.pipe(
+    Effect.catchTags({
+      ServerAuthMissingCredentialError: () => failEnvironmentAuthInvalid("missing_credential"),
+      ServerAuthInvalidCredentialError: () => failEnvironmentAuthInvalid("invalid_credential"),
+      ServerAuthSessionCredentialValidationError: failAuthenticationInternal,
+      ServerAuthDpopReplayStateRecordError: failAuthenticationInternal,
+      ServerAuthDpopReplayKeyCalculationError: failAuthenticationInternal,
+    }),
+  );
+
 export const requireEnvironmentScope = Effect.fn("environment.auth.requireScope")(function* (
   scope: AuthEnvironmentScope,
 ) {
@@ -168,13 +184,8 @@ export const environmentAuthenticatedAuthLayer = Layer.effect(
     return (httpEffect) =>
       Effect.gen(function* () {
         const request = yield* HttpServerRequest.HttpServerRequest;
-        const session = yield* serverAuth.authenticateHttpRequest(request).pipe(
-          Effect.catchIf(EnvironmentAuth.isServerAuthCredentialError, (error) =>
-            failEnvironmentAuthInvalid(EnvironmentAuth.serverAuthCredentialReason(error)),
-          ),
-          Effect.catchIf(EnvironmentAuth.isServerAuthInternalError, (error) =>
-            failEnvironmentInternal("internal_error", error),
-          ),
+        const session = yield* catchEnvironmentAuthenticationErrors(
+          serverAuth.authenticateHttpRequest(request),
         );
         return yield* httpEffect.pipe(
           Effect.provideService(EnvironmentAuthenticatedPrincipal, {
@@ -183,7 +194,11 @@ export const environmentAuthenticatedAuthLayer = Layer.effect(
           }),
           session.subject === "cloud-connect" ? traceAuthenticatedRelayRequest : identity,
         );
-      }).pipe(Effect.catchTag("EnvironmentAuthInvalidError", appendDpopChallengeOnUnauthorized));
+      }).pipe(
+        Effect.catchTags({
+          EnvironmentAuthInvalidError: appendDpopChallengeOnUnauthorized,
+        }),
+      );
   }),
 );
 
@@ -203,9 +218,11 @@ export const authHttpApiLayer = HttpApiBuilder.group(
             const request = yield* HttpServerRequest.HttpServerRequest;
             return yield* serverAuth.getSessionState(request);
           },
-          Effect.catchIf(EnvironmentAuth.isServerAuthInternalError, (error) =>
-            failEnvironmentInternal("internal_error", error),
-          ),
+          Effect.catchTags({
+            ServerAuthSessionCredentialValidationError: failAuthenticationInternal,
+            ServerAuthDpopReplayStateRecordError: failAuthenticationInternal,
+            ServerAuthDpopReplayKeyCalculationError: failAuthenticationInternal,
+          }),
         ),
       )
       .handle(
@@ -233,12 +250,14 @@ export const authHttpApiLayer = HttpApiBuilder.group(
             yield* appendCredentialResponseHeaders;
             return result.response;
           },
-          Effect.catchIf(EnvironmentAuth.isServerAuthCredentialError, (error) =>
-            failEnvironmentAuthInvalid(EnvironmentAuth.serverAuthCredentialReason(error)),
-          ),
-          Effect.catchIf(EnvironmentAuth.isServerAuthInternalError, (error) =>
-            failEnvironmentInternal("browser_session_issuance_failed", error),
-          ),
+          Effect.catchTags({
+            ServerAuthInvalidCredentialError: () =>
+              failEnvironmentAuthInvalid("invalid_credential"),
+            ServerAuthBootstrapCredentialValidationError: (error) =>
+              failEnvironmentInternal("browser_session_issuance_failed", error),
+            ServerAuthAuthenticatedSessionIssueError: (error) =>
+              failEnvironmentInternal("browser_session_issuance_failed", error),
+          }),
         ),
       )
       .handle(
@@ -268,14 +287,16 @@ export const authHttpApiLayer = HttpApiBuilder.group(
             }
             const proofKeyThumbprint = args.headers.dpop
               ? yield* verifyRequestDpopProof({ request }).pipe(
-                  Effect.catchIf(EnvironmentAuth.isServerAuthCredentialError, () =>
-                    appendDpopChallengeHeader.pipe(
-                      Effect.andThen(failEnvironmentAuthInvalid("invalid_credential")),
-                    ),
-                  ),
-                  Effect.catchIf(EnvironmentAuth.isServerAuthInternalError, (error) =>
-                    failEnvironmentInternal("access_token_issuance_failed", error),
-                  ),
+                  Effect.catchTags({
+                    ServerAuthInvalidCredentialError: () =>
+                      appendDpopChallengeHeader.pipe(
+                        Effect.andThen(failEnvironmentAuthInvalid("invalid_credential")),
+                      ),
+                    ServerAuthDpopReplayStateRecordError: (error) =>
+                      failEnvironmentInternal("access_token_issuance_failed", error),
+                    ServerAuthDpopReplayKeyCalculationError: (error) =>
+                      failEnvironmentInternal("access_token_issuance_failed", error),
+                  }),
                 )
               : undefined;
             yield* appendCredentialResponseHeaders;
@@ -296,15 +317,16 @@ export const authHttpApiLayer = HttpApiBuilder.group(
             );
           },
           traceRelayRequest,
-          Effect.catchIf(EnvironmentAuth.isServerAuthCredentialError, (error) =>
-            failEnvironmentAuthInvalid(EnvironmentAuth.serverAuthCredentialReason(error)),
-          ),
-          Effect.catchIf(EnvironmentAuth.isServerAuthInvalidRequestError, (error) =>
-            failEnvironmentInvalidRequest(EnvironmentAuth.serverAuthInvalidRequestReason(error)),
-          ),
-          Effect.catchIf(EnvironmentAuth.isServerAuthInternalError, (error) =>
-            failEnvironmentInternal("access_token_issuance_failed", error),
-          ),
+          Effect.catchTags({
+            ServerAuthInvalidCredentialError: () =>
+              failEnvironmentAuthInvalid("invalid_credential"),
+            ServerAuthScopeNotGrantedError: () =>
+              failEnvironmentInvalidRequest("scope_not_granted"),
+            ServerAuthBootstrapCredentialValidationError: (error) =>
+              failEnvironmentInternal("access_token_issuance_failed", error),
+            ServerAuthAuthenticatedAccessTokenIssueError: (error) =>
+              failEnvironmentInternal("access_token_issuance_failed", error),
+          }),
         ),
       )
       .handle(
@@ -316,9 +338,10 @@ export const authHttpApiLayer = HttpApiBuilder.group(
             yield* appendCredentialResponseHeaders;
             return yield* serverAuth.issueWebSocketTicket(session);
           },
-          Effect.catchIf(EnvironmentAuth.isServerAuthInternalError, (error) =>
-            failEnvironmentInternal("websocket_ticket_issuance_failed", error),
-          ),
+          Effect.catchTags({
+            ServerAuthWebSocketTokenIssueError: (error) =>
+              failEnvironmentInternal("websocket_ticket_issuance_failed", error),
+          }),
         ),
       )
       .handle(
@@ -341,9 +364,10 @@ export const authHttpApiLayer = HttpApiBuilder.group(
             }
             return yield* serverAuth.issuePairingCredential(args.payload);
           },
-          Effect.catchIf(EnvironmentAuth.isServerAuthInternalError, (error) =>
-            failEnvironmentInternal("pairing_credential_issuance_failed", error),
-          ),
+          Effect.catchTags({
+            ServerAuthPairingLinkCreationError: (error) =>
+              failEnvironmentInternal("pairing_credential_issuance_failed", error),
+          }),
         ),
       )
       .handle(
@@ -354,9 +378,10 @@ export const authHttpApiLayer = HttpApiBuilder.group(
             yield* requireEnvironmentScope(AuthAccessReadScope);
             return yield* serverAuth.listPairingLinks();
           },
-          Effect.catchIf(EnvironmentAuth.isServerAuthInternalError, (error) =>
-            failEnvironmentInternal("pairing_links_load_failed", error),
-          ),
+          Effect.catchTags({
+            ServerAuthPairingLinksListError: (error) =>
+              failEnvironmentInternal("pairing_links_load_failed", error),
+          }),
         ),
       )
       .handle(
@@ -368,9 +393,10 @@ export const authHttpApiLayer = HttpApiBuilder.group(
             const revoked = yield* serverAuth.revokePairingLink(args.payload.id);
             return { revoked };
           },
-          Effect.catchIf(EnvironmentAuth.isServerAuthInternalError, (error) =>
-            failEnvironmentInternal("pairing_link_revoke_failed", error),
-          ),
+          Effect.catchTags({
+            ServerAuthPairingLinkRevocationError: (error) =>
+              failEnvironmentInternal("pairing_link_revoke_failed", error),
+          }),
         ),
       )
       .handle(
@@ -381,9 +407,10 @@ export const authHttpApiLayer = HttpApiBuilder.group(
             const session = yield* requireEnvironmentScope(AuthAccessReadScope);
             return yield* serverAuth.listClientSessions(session.sessionId);
           },
-          Effect.catchIf(EnvironmentAuth.isServerAuthInternalError, (error) =>
-            failEnvironmentInternal("client_sessions_load_failed", error),
-          ),
+          Effect.catchTags({
+            ServerAuthSessionsListError: (error) =>
+              failEnvironmentInternal("client_sessions_load_failed", error),
+          }),
         ),
       )
       .handle(
@@ -398,12 +425,12 @@ export const authHttpApiLayer = HttpApiBuilder.group(
             );
             return { revoked };
           },
-          Effect.catchTag("ServerAuthForbiddenOperationError", () =>
-            failEnvironmentOperationForbidden("current_session_revoke_not_allowed"),
-          ),
-          Effect.catchIf(EnvironmentAuth.isServerAuthInternalError, (error) =>
-            failEnvironmentInternal("client_session_revoke_failed", error),
-          ),
+          Effect.catchTags({
+            ServerAuthForbiddenOperationError: () =>
+              failEnvironmentOperationForbidden("current_session_revoke_not_allowed"),
+            ServerAuthSessionRevocationError: (error) =>
+              failEnvironmentInternal("client_session_revoke_failed", error),
+          }),
         ),
       )
       .handle(
@@ -415,9 +442,10 @@ export const authHttpApiLayer = HttpApiBuilder.group(
             const revokedCount = yield* serverAuth.revokeOtherClientSessions(session.sessionId);
             return { revokedCount };
           },
-          Effect.catchIf(EnvironmentAuth.isServerAuthInternalError, (error) =>
-            failEnvironmentInternal("client_session_revoke_failed", error),
-          ),
+          Effect.catchTags({
+            ServerAuthOtherSessionsRevocationError: (error) =>
+              failEnvironmentInternal("client_session_revoke_failed", error),
+          }),
         ),
       );
   }),
diff --git a/apps/server/src/cloud/CliTokenManager.test.ts b/apps/server/src/cloud/CliTokenManager.test.ts
new file mode 100644
index 00000000000..e86dfe8cfed
--- /dev/null
+++ b/apps/server/src/cloud/CliTokenManager.test.ts
@@ -0,0 +1,184 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { describe, expect, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as PlatformError from "effect/PlatformError";
+import * as HttpClient from "effect/unstable/http/HttpClient";
+
+import * as ServerSecretStore from "../auth/ServerSecretStore.ts";
+import * as CliTokenManager from "./CliTokenManager.ts";
+
+const unusedSecretStoreOperation = () => Effect.die("unused secret-store operation");
+
+function makeSecretStore(
+  overrides: Partial<ServerSecretStore.ServerSecretStore["Service"]>,
+): ServerSecretStore.ServerSecretStore["Service"] {
+  return {
+    get: unusedSecretStoreOperation,
+    set: unusedSecretStoreOperation,
+    create: unusedSecretStoreOperation,
+    getOrCreateRandom: unusedSecretStoreOperation,
+    remove: unusedSecretStoreOperation,
+    ...overrides,
+  };
+}
+
+function makeTokenManager(secretStore: ServerSecretStore.ServerSecretStore["Service"]) {
+  return CliTokenManager.make.pipe(
+    Effect.provide(
+      Layer.mergeAll(
+        NodeServices.layer,
+        Layer.succeed(ServerSecretStore.ServerSecretStore, secretStore),
+        Layer.succeed(
+          HttpClient.HttpClient,
+          HttpClient.make(() => Effect.die("unused HTTP client")),
+        ),
+      ),
+    ),
+  );
+}
+
+describe("CloudCliTokenManager", () => {
+  it("redacts OAuth endpoint credentials while retaining exact causes", () => {
+    const tokenEndpoint =
+      "https://user:password@auth.example.test/private/token?client_secret=secret#fragment";
+    const redirectUri =
+      "https://callback-user:callback-password@localhost/private/callback?code=secret#fragment";
+    const cause = new Error("exchange failed");
+
+    const refreshError = CliTokenManager.CloudCliCredentialRefreshError.fromStage({
+      stage: "exchange-token",
+      tokenEndpoint,
+      cause,
+    });
+    const authorizationError = CliTokenManager.CloudCliAuthorizationError.fromStage({
+      stage: "exchange-token",
+      tokenEndpoint,
+      redirectUri,
+      cause,
+    });
+    const timeoutError = CliTokenManager.CloudCliAuthorizationTimeoutError.fromRedirectUri({
+      redirectUri,
+      timeoutMillis: 1000,
+      cause,
+    });
+
+    expect(refreshError).toMatchObject({
+      tokenEndpointInputLength: tokenEndpoint.length,
+      tokenEndpointProtocol: "https:",
+      tokenEndpointHostname: "auth.example.test",
+      cause,
+    });
+    expect(authorizationError).toMatchObject({
+      tokenEndpointInputLength: tokenEndpoint.length,
+      tokenEndpointHostname: "auth.example.test",
+      redirectUriInputLength: redirectUri.length,
+      redirectUriHostname: "localhost",
+      cause,
+    });
+    expect(timeoutError).toMatchObject({
+      redirectUriInputLength: redirectUri.length,
+      redirectUriHostname: "localhost",
+      cause,
+    });
+    expect(refreshError.cause).toBe(cause);
+    expect(authorizationError.cause).toBe(cause);
+    expect(timeoutError.cause).toBe(cause);
+    for (const error of [refreshError, authorizationError, timeoutError]) {
+      expect(error).not.toHaveProperty("tokenEndpoint");
+      expect(error).not.toHaveProperty("redirectUri");
+      const serialized = JSON.stringify(error);
+      for (const secret of [
+        "user:password",
+        "callback-user:callback-password",
+        "/private/",
+        "client_secret=secret",
+        "code=secret",
+        "#fragment",
+      ]) {
+        expect(error.message).not.toContain(secret);
+        expect(serialized).not.toContain(secret);
+      }
+    }
+  });
+
+  it.effect("retains secret context and cause when credential removal fails", () => {
+    const failure = new ServerSecretStore.SecretStoreRemoveError({
+      secretName: "cloud-cli-oauth-token",
+      secretPath: "/tmp/secrets/cloud-cli-oauth-token.bin",
+      cause: PlatformError.systemError({
+        _tag: "PermissionDenied",
+        module: "FileSystem",
+        method: "remove",
+        pathOrDescriptor: "/tmp/secrets/cloud-cli-oauth-token.bin",
+      }),
+    });
+
+    return Effect.gen(function* () {
+      const tokens = yield* makeTokenManager(
+        makeSecretStore({ remove: () => Effect.fail(failure) }),
+      );
+      const error = yield* Effect.flip(tokens.clear);
+
+      expect(error).toMatchObject({
+        _tag: "CloudCliCredentialRemovalError",
+        secretName: "cloud-cli-oauth-token",
+        cause: failure,
+      });
+      expect(error.message).toBe(
+        "Could not remove the stored T3 Connect CLI credential cloud-cli-oauth-token.",
+      );
+    });
+  });
+
+  it.effect("classifies credential read failures without replacing the cause", () => {
+    const failure = new ServerSecretStore.SecretStoreReadError({
+      secretName: "cloud-cli-oauth-token",
+      secretPath: "/tmp/secrets/cloud-cli-oauth-token.bin",
+      cause: PlatformError.systemError({
+        _tag: "PermissionDenied",
+        module: "FileSystem",
+        method: "readFile",
+        pathOrDescriptor: "/tmp/secrets/cloud-cli-oauth-token.bin",
+      }),
+    });
+
+    return Effect.gen(function* () {
+      const tokens = yield* makeTokenManager(makeSecretStore({ get: () => Effect.fail(failure) }));
+      const error = yield* Effect.flip(tokens.hasCredential);
+
+      expect(error).toMatchObject({
+        _tag: "CloudCliCredentialReadError",
+        stage: "read-credential",
+        secretName: "cloud-cli-oauth-token",
+        cause: failure,
+      });
+      expect(error.message).toBe(
+        "Could not inspect the stored T3 Connect CLI credential cloud-cli-oauth-token during read-credential.",
+      );
+    });
+  });
+
+  it.effect("classifies malformed persisted credentials as refresh decode failures", () =>
+    Effect.gen(function* () {
+      const tokens = yield* makeTokenManager(
+        makeSecretStore({
+          get: () =>
+            Effect.succeed(Option.some(new TextEncoder().encode("not valid credential JSON"))),
+        }),
+      );
+      const error = yield* Effect.flip(tokens.getExisting);
+
+      expect(error).toMatchObject({
+        _tag: "CloudCliCredentialRefreshError",
+        stage: "decode-credential",
+        secretName: "cloud-cli-oauth-token",
+        cause: { _tag: "SchemaError" },
+      });
+      expect(error.message).toBe(
+        "Could not refresh the T3 Connect CLI credential cloud-cli-oauth-token during decode-credential.",
+      );
+    }),
+  );
+});
diff --git a/apps/server/src/cloud/CliTokenManager.ts b/apps/server/src/cloud/CliTokenManager.ts
index 00709370b26..9d869059bcf 100644
--- a/apps/server/src/cloud/CliTokenManager.ts
+++ b/apps/server/src/cloud/CliTokenManager.ts
@@ -20,6 +20,7 @@ import * as HttpClientResponse from "effect/unstable/http/HttpClientResponse";
 import * as HttpRouter from "effect/unstable/http/HttpRouter";
 import * as HttpServerRequest from "effect/unstable/http/HttpServerRequest";
 import * as HttpServerResponse from "effect/unstable/http/HttpServerResponse";
+import { getUrlDiagnostics } from "@t3tools/shared/urlDiagnostics";
 
 import * as ServerSecretStore from "../auth/ServerSecretStore.ts";
 import { cloudCliOAuthConfig, type CloudCliOAuthConfig } from "./publicConfig.ts";
@@ -27,6 +28,8 @@ import { cloudCliOAuthConfig, type CloudCliOAuthConfig } from "./publicConfig.ts
 const CLOUD_CLI_OAUTH_TOKEN_SECRET = "cloud-cli-oauth-token";
 const CLOUD_CLI_OAUTH_CALLBACK_TIMEOUT = Duration.minutes(10);
 const CLOUD_CLI_OAUTH_REFRESH_EARLY_MS = Duration.toMillis(Duration.minutes(5));
+const CLOUD_CLI_OAUTH_CALLBACK_HOST = "127.0.0.1";
+const CLOUD_CLI_OAUTH_CALLBACK_PORT = 34338;
 
 const PersistedToken = Schema.Struct({
   accessToken: Schema.String,
@@ -46,48 +49,223 @@ const OAuthTokenResponse = Schema.Struct({
   token_type: Schema.String,
 });
 
+type CredentialReadFailure = ServerSecretStore.SecretStoreReadError | Schema.SchemaError;
+
+type CredentialPersistFailure =
+  | Schema.SchemaError
+  | ServerSecretStore.SecretStoreTemporaryPathGenerationError
+  | ServerSecretStore.SecretStorePersistError;
+
+const CloudCliCredentialRefreshStage = Schema.Literals([
+  "read-credential",
+  "decode-credential",
+  "load-oauth-config",
+  "exchange-token",
+  "encode-credential",
+  "persist-credential",
+]);
+type CloudCliCredentialRefreshStage = typeof CloudCliCredentialRefreshStage.Type;
+
+const CloudCliAuthorizationStage = Schema.Literals([
+  "load-oauth-config",
+  "prepare-pkce",
+  "start-callback-server",
+  "exchange-token",
+  "encode-credential",
+  "persist-credential",
+]);
+type CloudCliAuthorizationStage = typeof CloudCliAuthorizationStage.Type;
+
+function tokenEndpointDiagnosticFields(tokenEndpoint: string | undefined) {
+  if (tokenEndpoint === undefined) return {};
+  const diagnostics = getUrlDiagnostics(tokenEndpoint);
+  return {
+    tokenEndpointInputLength: diagnostics.inputLength,
+    ...(diagnostics.protocol === undefined ? {} : { tokenEndpointProtocol: diagnostics.protocol }),
+    ...(diagnostics.hostname === undefined ? {} : { tokenEndpointHostname: diagnostics.hostname }),
+  };
+}
+
+function redirectUriDiagnosticFields(redirectUri: string | undefined) {
+  if (redirectUri === undefined) return {};
+  const diagnostics = getUrlDiagnostics(redirectUri);
+  return {
+    redirectUriInputLength: diagnostics.inputLength,
+    ...(diagnostics.protocol === undefined ? {} : { redirectUriProtocol: diagnostics.protocol }),
+    ...(diagnostics.hostname === undefined ? {} : { redirectUriHostname: diagnostics.hostname }),
+  };
+}
+
 export class CloudCliCredentialRemovalError extends Schema.TaggedErrorClass<CloudCliCredentialRemovalError>()(
   "CloudCliCredentialRemovalError",
-  { cause: Schema.Defect() },
+  {
+    secretName: Schema.Literal(CLOUD_CLI_OAUTH_TOKEN_SECRET),
+    cause: Schema.Defect(),
+  },
 ) {
   override get message(): string {
-    return "Could not remove the stored T3 Connect CLI credential.";
+    return `Could not remove the stored T3 Connect CLI credential ${this.secretName}.`;
   }
 }
 
 export class CloudCliCredentialRefreshError extends Schema.TaggedErrorClass<CloudCliCredentialRefreshError>()(
   "CloudCliCredentialRefreshError",
-  { cause: Schema.Defect() },
+  {
+    stage: CloudCliCredentialRefreshStage,
+    secretName: Schema.Literal(CLOUD_CLI_OAUTH_TOKEN_SECRET),
+    tokenEndpointInputLength: Schema.optionalKey(Schema.Number),
+    tokenEndpointProtocol: Schema.optionalKey(Schema.String),
+    tokenEndpointHostname: Schema.optionalKey(Schema.String),
+    cause: Schema.Defect(),
+  },
 ) {
+  static fromStage(input: {
+    readonly stage: CloudCliCredentialRefreshStage;
+    readonly cause: unknown;
+    readonly tokenEndpoint?: string;
+  }): CloudCliCredentialRefreshError {
+    return new CloudCliCredentialRefreshError({
+      stage: input.stage,
+      secretName: CLOUD_CLI_OAUTH_TOKEN_SECRET,
+      ...tokenEndpointDiagnosticFields(input.tokenEndpoint),
+      cause: input.cause,
+    });
+  }
+
+  static fromCredentialRead(cause: CredentialReadFailure): CloudCliCredentialRefreshError {
+    return new CloudCliCredentialRefreshError({
+      stage: cause._tag === "SecretStoreReadError" ? "read-credential" : "decode-credential",
+      secretName: CLOUD_CLI_OAUTH_TOKEN_SECRET,
+      cause,
+    });
+  }
+
+  static fromCredentialPersist(cause: CredentialPersistFailure): CloudCliCredentialRefreshError {
+    return new CloudCliCredentialRefreshError({
+      stage: cause._tag === "SchemaError" ? "encode-credential" : "persist-credential",
+      secretName: CLOUD_CLI_OAUTH_TOKEN_SECRET,
+      cause,
+    });
+  }
+
   override get message(): string {
-    return "Could not refresh the T3 Connect CLI credential.";
+    const tokenEndpoint =
+      this.tokenEndpointInputLength === undefined
+        ? ""
+        : ` using the token endpoint${this.tokenEndpointHostname ? ` at ${this.tokenEndpointHostname}` : ""} (input length ${this.tokenEndpointInputLength})`;
+    return `Could not refresh the T3 Connect CLI credential ${this.secretName} during ${this.stage}${tokenEndpoint}.`;
   }
 }
 
 export class CloudCliCredentialReadError extends Schema.TaggedErrorClass<CloudCliCredentialReadError>()(
   "CloudCliCredentialReadError",
-  { cause: Schema.Defect() },
+  {
+    stage: Schema.Literals(["read-credential", "decode-credential"]),
+    secretName: Schema.Literal(CLOUD_CLI_OAUTH_TOKEN_SECRET),
+    cause: Schema.Defect(),
+  },
 ) {
+  static fromCredentialRead(cause: CredentialReadFailure): CloudCliCredentialReadError {
+    return new CloudCliCredentialReadError({
+      stage: cause._tag === "SecretStoreReadError" ? "read-credential" : "decode-credential",
+      secretName: CLOUD_CLI_OAUTH_TOKEN_SECRET,
+      cause,
+    });
+  }
+
   override get message(): string {
-    return "Could not read the stored T3 Connect CLI credential.";
+    return `Could not inspect the stored T3 Connect CLI credential ${this.secretName} during ${this.stage}.`;
   }
 }
 
 export class CloudCliAuthorizationError extends Schema.TaggedErrorClass<CloudCliAuthorizationError>()(
   "CloudCliAuthorizationError",
-  { cause: Schema.Defect() },
+  {
+    stage: CloudCliAuthorizationStage,
+    secretName: Schema.Literal(CLOUD_CLI_OAUTH_TOKEN_SECRET),
+    tokenEndpointInputLength: Schema.optionalKey(Schema.Number),
+    tokenEndpointProtocol: Schema.optionalKey(Schema.String),
+    tokenEndpointHostname: Schema.optionalKey(Schema.String),
+    redirectUriInputLength: Schema.optionalKey(Schema.Number),
+    redirectUriProtocol: Schema.optionalKey(Schema.String),
+    redirectUriHostname: Schema.optionalKey(Schema.String),
+    callbackHost: Schema.optional(Schema.String),
+    callbackPort: Schema.optional(Schema.Number),
+    cause: Schema.Defect(),
+  },
 ) {
+  static fromStage(input: {
+    readonly stage: CloudCliAuthorizationStage;
+    readonly cause: unknown;
+    readonly tokenEndpoint?: string;
+    readonly redirectUri?: string;
+    readonly callbackHost?: string;
+    readonly callbackPort?: number;
+  }): CloudCliAuthorizationError {
+    return new CloudCliAuthorizationError({
+      stage: input.stage,
+      secretName: CLOUD_CLI_OAUTH_TOKEN_SECRET,
+      ...tokenEndpointDiagnosticFields(input.tokenEndpoint),
+      ...redirectUriDiagnosticFields(input.redirectUri),
+      ...(input.callbackHost === undefined ? {} : { callbackHost: input.callbackHost }),
+      ...(input.callbackPort === undefined ? {} : { callbackPort: input.callbackPort }),
+      cause: input.cause,
+    });
+  }
+
+  static fromCredentialPersist(cause: CredentialPersistFailure): CloudCliAuthorizationError {
+    return new CloudCliAuthorizationError({
+      stage: cause._tag === "SchemaError" ? "encode-credential" : "persist-credential",
+      secretName: CLOUD_CLI_OAUTH_TOKEN_SECRET,
+      cause,
+    });
+  }
+
   override get message(): string {
-    return "Could not authorize the T3 Connect CLI.";
+    const tokenEndpoint =
+      this.tokenEndpointInputLength === undefined
+        ? ""
+        : ` using the token endpoint${this.tokenEndpointHostname ? ` at ${this.tokenEndpointHostname}` : ""} (input length ${this.tokenEndpointInputLength})`;
+    const redirectUri =
+      this.redirectUriInputLength === undefined
+        ? ""
+        : ` with a callback URI input of length ${this.redirectUriInputLength}`;
+    const callbackAddress =
+      this.callbackHost && this.callbackPort !== undefined
+        ? ` on ${this.callbackHost}:${this.callbackPort}`
+        : "";
+    return `Could not authorize the T3 Connect CLI credential ${this.secretName} during ${this.stage}${tokenEndpoint}${redirectUri}${callbackAddress}.`;
   }
 }
 
 export class CloudCliAuthorizationTimeoutError extends Schema.TaggedErrorClass<CloudCliAuthorizationTimeoutError>()(
   "CloudCliAuthorizationTimeoutError",
-  { cause: Schema.Defect() },
+  {
+    redirectUriInputLength: Schema.Number,
+    redirectUriProtocol: Schema.optionalKey(Schema.String),
+    redirectUriHostname: Schema.optionalKey(Schema.String),
+    timeoutMillis: Schema.Number,
+    cause: Schema.Defect(),
+  },
 ) {
+  static fromRedirectUri(input: {
+    readonly redirectUri: string;
+    readonly timeoutMillis: number;
+    readonly cause: unknown;
+  }): CloudCliAuthorizationTimeoutError {
+    const diagnostics = getUrlDiagnostics(input.redirectUri);
+    return new CloudCliAuthorizationTimeoutError({
+      redirectUriInputLength: diagnostics.inputLength,
+      ...(diagnostics.protocol === undefined ? {} : { redirectUriProtocol: diagnostics.protocol }),
+      ...(diagnostics.hostname === undefined ? {} : { redirectUriHostname: diagnostics.hostname }),
+      timeoutMillis: input.timeoutMillis,
+      cause: input.cause,
+    });
+  }
+
   override get message(): string {
-    return "Timed out waiting for T3 Connect authorization.";
+    const callback = this.redirectUriHostname ? ` for ${this.redirectUriHostname}` : "";
+    return `Timed out after ${this.timeoutMillis}ms waiting for T3 Connect authorization${callback} (callback URI input length ${this.redirectUriInputLength}).`;
   }
 }
 
@@ -103,18 +281,21 @@ export type CloudCliTokenManagerError = typeof CloudCliTokenManagerError.Type;
 export class CloudCliTokenManager extends Context.Service<
   CloudCliTokenManager,
   {
-    readonly get: Effect.Effect<PersistedToken, CloudCliTokenManagerError>;
-    readonly getExisting: Effect.Effect<Option.Option<PersistedToken>, CloudCliTokenManagerError>;
-    readonly hasCredential: Effect.Effect<boolean, CloudCliTokenManagerError>;
-    readonly clear: Effect.Effect<void, CloudCliTokenManagerError>;
+    readonly get: Effect.Effect<
+      PersistedToken,
+      | CloudCliCredentialRefreshError
+      | CloudCliAuthorizationError
+      | CloudCliAuthorizationTimeoutError
+    >;
+    readonly getExisting: Effect.Effect<
+      Option.Option<PersistedToken>,
+      CloudCliCredentialRefreshError
+    >;
+    readonly hasCredential: Effect.Effect<boolean, CloudCliCredentialReadError>;
+    readonly clear: Effect.Effect<void, CloudCliCredentialRemovalError>;
   }
 >()("t3/cloud/CliTokenManager/CloudCliTokenManager") {}
 
-const wrapError =
-  <WrappedError extends CloudCliTokenManagerError>(makeError: (cause: unknown) => WrappedError) =>
-  <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, WrappedError, R> =>
-    effect.pipe(Effect.mapError(makeError));
-
 function stringToBytes(value: string): Uint8Array {
   return new TextEncoder().encode(value);
 }
@@ -134,9 +315,15 @@ export const make = Effect.gen(function* () {
     return token;
   });
 
-  const clear = secrets
-    .remove(CLOUD_CLI_OAUTH_TOKEN_SECRET)
-    .pipe(wrapError((cause) => new CloudCliCredentialRemovalError({ cause })));
+  const clear = secrets.remove(CLOUD_CLI_OAUTH_TOKEN_SECRET).pipe(
+    Effect.mapError(
+      (cause) =>
+        new CloudCliCredentialRemovalError({
+          secretName: CLOUD_CLI_OAUTH_TOKEN_SECRET,
+          cause,
+        }),
+    ),
+  );
 
   const read = Effect.fn("cloud.cli_token.read")(function* () {
     const encoded = yield* secrets.get(CLOUD_CLI_OAUTH_TOKEN_SECRET);
@@ -162,21 +349,54 @@ export const make = Effect.gen(function* () {
   });
 
   const refresh = Effect.fn("cloud.cli_token.refresh")(function* (token: PersistedToken) {
-    const metadata = yield* cloudCliOAuthConfig;
+    const metadata = yield* cloudCliOAuthConfig.pipe(
+      Effect.mapError((cause) =>
+        CloudCliCredentialRefreshError.fromStage({
+          stage: "load-oauth-config",
+          cause,
+        }),
+      ),
+    );
     return yield* exchangeToken(metadata, {
       grant_type: "refresh_token",
       refresh_token: token.refreshToken,
       client_id: metadata.clientId,
-    });
+    }).pipe(
+      Effect.mapError((cause) =>
+        CloudCliCredentialRefreshError.fromStage({
+          stage: "exchange-token",
+          tokenEndpoint: metadata.tokenEndpoint,
+          cause,
+        }),
+      ),
+    );
   });
 
   const login = Effect.fn("cloud.cli_token.login")(function* () {
-    const metadata = yield* cloudCliOAuthConfig;
-    const verifier = Encoding.encodeBase64Url(yield* crypto.randomBytes(32));
-    const challenge = Encoding.encodeBase64Url(
-      yield* crypto.digest("SHA-256", new TextEncoder().encode(verifier)),
+    const metadata = yield* cloudCliOAuthConfig.pipe(
+      Effect.mapError((cause) =>
+        CloudCliAuthorizationError.fromStage({
+          stage: "load-oauth-config",
+          cause,
+        }),
+      ),
+    );
+    const { challenge, state, verifier } = yield* Effect.gen(function* () {
+      const verifier = Encoding.encodeBase64Url(yield* crypto.randomBytes(32));
+      const challenge = Encoding.encodeBase64Url(
+        yield* crypto.digest("SHA-256", new TextEncoder().encode(verifier)),
+      );
+      const state = yield* crypto.randomUUIDv4;
+      return { challenge, state, verifier };
+    }).pipe(
+      Effect.mapError((cause) =>
+        CloudCliAuthorizationError.fromStage({
+          stage: "prepare-pkce",
+          redirectUri: metadata.redirectUri,
+          cause,
+        }),
+      ),
     );
-    const state = yield* crypto.randomUUIDv4;
     const callback = yield* Deferred.make<string>();
     const callbackRoute = HttpRouter.add(
       "GET",
@@ -207,12 +427,21 @@ export const make = Effect.gen(function* () {
     }).pipe(
       Layer.provide(
         NodeHttpServer.layer(NodeHttp.createServer, {
-          host: "127.0.0.1",
-          port: 34338,
+          host: CLOUD_CLI_OAUTH_CALLBACK_HOST,
+          port: CLOUD_CLI_OAUTH_CALLBACK_PORT,
           disablePreemptiveShutdown: true,
         }),
       ),
       Layer.build,
+      Effect.mapError((cause) =>
+        CloudCliAuthorizationError.fromStage({
+          stage: "start-callback-server",
+          redirectUri: metadata.redirectUri,
+          callbackHost: CLOUD_CLI_OAUTH_CALLBACK_HOST,
+          callbackPort: CLOUD_CLI_OAUTH_CALLBACK_PORT,
+          cause,
+        }),
+      ),
     );
     const authorizationUrl = new URL(metadata.authorizationEndpoint);
     authorizationUrl.searchParams.set("client_id", metadata.clientId);
@@ -225,13 +454,16 @@ export const make = Effect.gen(function* () {
     yield* Console.log(`Open this URL to authorize T3 Connect:\n${authorizationUrl.toString()}\n`);
     const code = yield* Deferred.await(callback).pipe(
       Effect.timeout(CLOUD_CLI_OAUTH_CALLBACK_TIMEOUT),
-      Effect.catchTag("TimeoutError", (cause) =>
-        Effect.fail(
-          new CloudCliAuthorizationTimeoutError({
-            cause,
-          }),
-        ),
-      ),
+      Effect.catchTags({
+        TimeoutError: (cause) =>
+          Effect.fail(
+            CloudCliAuthorizationTimeoutError.fromRedirectUri({
+              redirectUri: metadata.redirectUri,
+              timeoutMillis: Duration.toMillis(CLOUD_CLI_OAUTH_CALLBACK_TIMEOUT),
+              cause,
+            }),
+          ),
+      }),
     );
     return yield* exchangeToken(metadata, {
       grant_type: "authorization_code",
@@ -239,26 +471,43 @@ export const make = Effect.gen(function* () {
       redirect_uri: metadata.redirectUri,
       client_id: metadata.clientId,
       code_verifier: verifier,
-    });
+    }).pipe(
+      Effect.mapError((cause) =>
+        CloudCliAuthorizationError.fromStage({
+          stage: "exchange-token",
+          tokenEndpoint: metadata.tokenEndpoint,
+          redirectUri: metadata.redirectUri,
+          cause,
+        }),
+      ),
+    );
   });
 
   const getExistingNoLock = Effect.fn("cloud.cli_token.get_existing_no_lock")(function* () {
-    const token = yield* read();
+    const token = yield* read().pipe(
+      Effect.mapError(CloudCliCredentialRefreshError.fromCredentialRead),
+    );
     if (Option.isNone(token)) return token;
     const now = yield* Clock.currentTimeMillis;
     if (token.value.expiresAtEpochMs - CLOUD_CLI_OAUTH_REFRESH_EARLY_MS > now) {
       return token;
     }
-    return Option.some(yield* refresh(token.value).pipe(Effect.flatMap(persist)));
+    return Option.some(
+      yield* refresh(token.value).pipe(
+        Effect.flatMap((refreshed) =>
+          persist(refreshed).pipe(
+            Effect.mapError(CloudCliCredentialRefreshError.fromCredentialPersist),
+          ),
+        ),
+      ),
+    );
   });
 
-  const getExisting = semaphore.withPermits(1)(
-    getExistingNoLock().pipe(wrapError((cause) => new CloudCliCredentialRefreshError({ cause }))),
-  );
+  const getExisting = semaphore.withPermits(1)(getExistingNoLock());
   const hasCredential = semaphore.withPermits(1)(
     read().pipe(
       Effect.map(Option.isSome),
-      wrapError((cause) => new CloudCliCredentialReadError({ cause })),
+      Effect.mapError(CloudCliCredentialReadError.fromCredentialRead),
     ),
   );
   const get = semaphore.withPermits(1)(
@@ -266,8 +515,14 @@ export const make = Effect.gen(function* () {
       const token = yield* getExistingNoLock();
       return Option.isSome(token)
         ? token.value
-        : yield* Effect.scoped(login()).pipe(Effect.flatMap(persist));
-    }).pipe(wrapError((cause) => new CloudCliAuthorizationError({ cause }))),
+        : yield* Effect.scoped(login()).pipe(
+            Effect.flatMap((authorized) =>
+              persist(authorized).pipe(
+                Effect.mapError(CloudCliAuthorizationError.fromCredentialPersist),
+              ),
+            ),
+          );
+    }),
   );
 
   return CloudCliTokenManager.of({ get, getExisting, hasCredential, clear });
diff --git a/apps/server/src/cloud/environmentKeys.test.ts b/apps/server/src/cloud/environmentKeys.test.ts
index 48c44ccc48a..a2fef8c8b0b 100644
--- a/apps/server/src/cloud/environmentKeys.test.ts
+++ b/apps/server/src/cloud/environmentKeys.test.ts
@@ -66,7 +66,9 @@ it.layer(NodeServices.layer)("getOrCreateEnvironmentKeyPairFromSecretStore", (it
             Effect.flatMap(() =>
               Effect.fail(
                 new ServerSecretStore.SecretStorePersistError({
-                  resource: "environment signing key pair",
+                  operation: "create",
+                  secretName: "cloud-link-ed25519-key-pair",
+                  secretPath: "cloud-link-ed25519-key-pair.bin",
                   cause: PlatformError.systemError({
                     _tag: "AlreadyExists",
                     module: "FileSystem",
@@ -87,4 +89,24 @@ it.layer(NodeServices.layer)("getOrCreateEnvironmentKeyPairFromSecretStore", (it
       });
     }),
   );
+
+  it.effect("retains the secret name and decode cause for malformed keypairs", () =>
+    Effect.gen(function* () {
+      const secretStore = {
+        get: () => Effect.succeed(Option.some(new TextEncoder().encode("not-json"))),
+        set: unusedSecretStoreOperation,
+        create: unusedSecretStoreOperation,
+        getOrCreateRandom: unusedSecretStoreOperation,
+        remove: unusedSecretStoreOperation,
+      } satisfies ServerSecretStore.ServerSecretStore["Service"];
+
+      const error = yield* getOrCreateEnvironmentKeyPairFromSecretStore(secretStore).pipe(
+        Effect.flip,
+      );
+
+      assert.instanceOf(error, ServerSecretStore.SecretStoreDecodeError);
+      assert.equal(error.secretName, "cloud-link-ed25519-key-pair");
+      assert.exists(error.cause);
+    }),
+  );
 });
diff --git a/apps/server/src/cloud/environmentKeys.ts b/apps/server/src/cloud/environmentKeys.ts
index 1d0cde91bf4..f10a166cec4 100644
--- a/apps/server/src/cloud/environmentKeys.ts
+++ b/apps/server/src/cloud/environmentKeys.ts
@@ -27,17 +27,6 @@ function stringToBytes(value: string): Uint8Array {
   return new TextEncoder().encode(value);
 }
 
-const KEY_PAIR_RESOURCE = "environment signing key pair";
-
-const keyPairDecodeError = (cause: unknown): ServerSecretStore.SecretStoreDecodeError =>
-  new ServerSecretStore.SecretStoreDecodeError({ resource: KEY_PAIR_RESOURCE, cause });
-
-const keyPairEncodeError = (cause: unknown): ServerSecretStore.SecretStoreEncodeError =>
-  new ServerSecretStore.SecretStoreEncodeError({ resource: KEY_PAIR_RESOURCE, cause });
-
-const keyPairConcurrentReadError = (): ServerSecretStore.SecretStoreConcurrentReadError =>
-  new ServerSecretStore.SecretStoreConcurrentReadError({ resource: KEY_PAIR_RESOURCE });
-
 const readEnvironmentKeyPair = Effect.fn("readEnvironmentKeyPair")(function* (
   secrets: ServerSecretStore.ServerSecretStore["Service"],
 ) {
@@ -46,7 +35,13 @@ const readEnvironmentKeyPair = Effect.fn("readEnvironmentKeyPair")(function* (
     return Option.none<EnvironmentKeyPair>();
   }
   const decoded = yield* decodeEnvironmentKeyPair(bytesToString(encoded.value)).pipe(
-    Effect.mapError(keyPairDecodeError),
+    Effect.mapError(
+      (cause) =>
+        new ServerSecretStore.SecretStoreDecodeError({
+          secretName: CLOUD_LINK_KEY_PAIR,
+          cause,
+        }),
+    ),
   );
   return Option.some(decoded);
 });
@@ -56,22 +51,35 @@ const persistEnvironmentKeyPair = Effect.fn("persistEnvironmentKeyPair")(functio
   keyPair: EnvironmentKeyPair,
 ) {
   const encoded = yield* encodeEnvironmentKeyPair(keyPair).pipe(
-    Effect.mapError(keyPairEncodeError),
+    Effect.mapError(
+      (cause) =>
+        new ServerSecretStore.SecretStoreEncodeError({
+          secretName: CLOUD_LINK_KEY_PAIR,
+          cause,
+        }),
+    ),
   );
   return yield* secrets.create(CLOUD_LINK_KEY_PAIR, stringToBytes(encoded)).pipe(
     Effect.as(keyPair),
-    Effect.catchIf(ServerSecretStore.isSecretStoreError, (error) =>
-      ServerSecretStore.isSecretAlreadyExistsError(error)
-        ? readEnvironmentKeyPair(secrets).pipe(
-            Effect.flatMap(
-              Option.match({
-                onSome: Effect.succeed,
-                onNone: () => Effect.fail(keyPairConcurrentReadError()),
-              }),
-            ),
-          )
-        : Effect.fail(error),
-    ),
+    Effect.catchTags({
+      SecretStorePersistError: (error) =>
+        ServerSecretStore.isSecretAlreadyExistsError(error)
+          ? readEnvironmentKeyPair(secrets).pipe(
+              Effect.flatMap(
+                Option.match({
+                  onSome: Effect.succeed,
+                  onNone: () =>
+                    Effect.fail(
+                      new ServerSecretStore.SecretStoreConcurrentReadError({
+                        secretName: CLOUD_LINK_KEY_PAIR,
+                        cause: error,
+                      }),
+                    ),
+                }),
+              ),
+            )
+          : Effect.fail(error),
+    }),
   );
 });
 
diff --git a/apps/server/src/cloud/http.test.ts b/apps/server/src/cloud/http.test.ts
index ed2e5a4cf75..26b4646fea6 100644
--- a/apps/server/src/cloud/http.test.ts
+++ b/apps/server/src/cloud/http.test.ts
@@ -1,23 +1,45 @@
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { describe, expect, it } from "@effect/vitest";
+import * as ConfigProvider from "effect/ConfigProvider";
 import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Logger from "effect/Logger";
 import * as Option from "effect/Option";
 import * as PlatformError from "effect/PlatformError";
+import * as Schema from "effect/Schema";
 import * as Tracer from "effect/Tracer";
-import { HttpClient, HttpServerRequest } from "effect/unstable/http";
+import * as HttpClient from "effect/unstable/http/HttpClient";
+import * as HttpClientError from "effect/unstable/http/HttpClientError";
+import * as HttpClientRequest from "effect/unstable/http/HttpClientRequest";
+import * as HttpClientResponse from "effect/unstable/http/HttpClientResponse";
+import * as HttpServerRequest from "effect/unstable/http/HttpServerRequest";
+import { EnvironmentHttpInternalServerError } from "@t3tools/contracts";
 
 import { RelayClientTracer } from "@t3tools/shared/relayTracing";
 import * as EnvironmentAuth from "../auth/EnvironmentAuth.ts";
 import * as ServerSecretStore from "../auth/ServerSecretStore.ts";
 import * as ServerEnvironment from "../environment/ServerEnvironment.ts";
 import * as CliTokenManager from "./CliTokenManager.ts";
-import { consumeCloudReplayGuards, reconcileDesiredCloudLink } from "./http.ts";
+import {
+  CloudRelayRequestError,
+  consumeCloudReplayGuards,
+  reconcileDesiredCloudLink,
+} from "./http.ts";
 import * as ManagedEndpointRuntime from "./ManagedEndpointRuntime.ts";
 import { traceAuthenticatedRelayRequest, traceRelayRequest } from "./traceRelayRequest.ts";
 
+const encodeEnvironmentHttpInternalServerError = Schema.encodeUnknownSync(
+  EnvironmentHttpInternalServerError,
+);
+const decodeEnvironmentHttpInternalServerError = Schema.decodeUnknownSync(
+  EnvironmentHttpInternalServerError,
+);
+
 const storeFailure = (tag: "AlreadyExists" | "PermissionDenied") =>
   new ServerSecretStore.SecretStorePersistError({
-    resource: "cloud replay guard",
+    operation: "create",
+    secretName: "cloud replay guard",
+    secretPath: "cloud-replay-guard.bin",
     cause: PlatformError.systemError({
       _tag: tag,
       module: "FileSystem",
@@ -40,6 +62,56 @@ function makeSecretStore(
   };
 }
 
+function reconcileWith(input: {
+  readonly getExisting: CliTokenManager.CloudCliTokenManager["Service"]["getExisting"];
+  readonly httpClient?: HttpClient.HttpClient;
+  readonly secretStore?: ServerSecretStore.ServerSecretStore["Service"];
+  readonly env?: Readonly<Record<string, string>>;
+}) {
+  return reconcileDesiredCloudLink("http://127.0.0.1:3774").pipe(
+    Effect.provideService(
+      ServerSecretStore.ServerSecretStore,
+      input.secretStore ?? makeSecretStore(unusedSecretStoreOperation),
+    ),
+    Effect.provideService(
+      ServerEnvironment.ServerEnvironment,
+      ServerEnvironment.ServerEnvironment.of({
+        getEnvironmentId: unusedSecretStoreOperation(),
+        getDescriptor: unusedSecretStoreOperation(),
+      }),
+    ),
+    Effect.provideService(
+      ManagedEndpointRuntime.CloudManagedEndpointRuntime,
+      ManagedEndpointRuntime.CloudManagedEndpointRuntime.of({
+        applyConfig: unusedSecretStoreOperation,
+      } satisfies ManagedEndpointRuntime.CloudManagedEndpointRuntime["Service"]),
+    ),
+    Effect.provideService(
+      EnvironmentAuth.EnvironmentAuth,
+      EnvironmentAuth.EnvironmentAuth.of({} as EnvironmentAuth.EnvironmentAuth["Service"]),
+    ),
+    Effect.provideService(
+      CliTokenManager.CloudCliTokenManager,
+      CliTokenManager.CloudCliTokenManager.of({
+        get: unusedSecretStoreOperation(),
+        getExisting: input.getExisting,
+        hasCredential: unusedSecretStoreOperation(),
+        clear: unusedSecretStoreOperation(),
+      }),
+    ),
+    Effect.provideService(
+      HttpClient.HttpClient,
+      input.httpClient ?? HttpClient.make(() => unusedSecretStoreOperation()),
+    ),
+    Effect.provide(
+      Layer.mergeAll(
+        NodeServices.layer,
+        ConfigProvider.layer(ConfigProvider.fromEnv({ env: input.env ?? {} })),
+      ),
+    ),
+  );
+}
+
 it("preserves messages surfaced by cloud 500 responses", () => {
   const cause = new Error("cloud operation failed");
 
@@ -93,6 +165,84 @@ describe("consumeCloudReplayGuards", () => {
   );
 });
 
+describe("CloudRelayRequestError", () => {
+  it("classifies response failures without deriving its message from the cause", () => {
+    const requestUrl =
+      "https://relay-user:relay-password@relay.example.test/private/environment-links?token=relay-secret#relay-fragment";
+    const request = HttpClientRequest.post(requestUrl);
+    const response = HttpClientResponse.fromWeb(
+      request,
+      new Response("sensitive upstream response", { status: 502 }),
+    );
+    const upstreamCause = new Error("sensitive upstream response details");
+    const cause = new HttpClientError.HttpClientError({
+      reason: new HttpClientError.StatusCodeError({
+        request,
+        response,
+        cause: upstreamCause,
+      }),
+    });
+
+    const error = CloudRelayRequestError.fromClientFailure({
+      operation: "create-environment-link",
+      url: request.url,
+      cause,
+    });
+
+    expect(error).toMatchObject({
+      operation: "create-environment-link",
+      phase: "check-response-status",
+      method: "POST",
+      requestUrlInputLength: requestUrl.length,
+      requestUrlProtocol: "https:",
+      requestUrlHostname: "relay.example.test",
+      responseStatus: 502,
+      cause,
+    });
+    expect(error.cause).toBe(cause);
+    expect(error).not.toHaveProperty("url");
+    expect(error.message).toBe(
+      "T3 Connect relay create-environment-link failed during check-response-status with response status 502.",
+    );
+    expect(error.message).not.toContain(upstreamCause.message);
+    for (const secret of [
+      "relay-user",
+      "relay-password",
+      "/private/environment-links",
+      "relay-secret",
+      "relay-fragment",
+    ]) {
+      expect(error.message).not.toContain(secret);
+      expect(Object.values(error).join(" ")).not.toContain(secret);
+    }
+  });
+});
+
+it("keeps internal causes out of encoded HTTP error bodies", () => {
+  const cause = new Error("private upstream detail");
+  const error = new EnvironmentHttpInternalServerError({
+    operation: "generate_link_proof",
+    cause,
+  });
+
+  expect(error.cause).toBe(cause);
+  expect(encodeEnvironmentHttpInternalServerError(error)).toEqual({
+    _tag: "EnvironmentHttpInternalServerError",
+    operation: "generate_link_proof",
+    message: "Could not generate environment link proof.",
+  });
+});
+
+it("decodes legacy message-only HTTP errors during rolling deployments", () => {
+  const error = decodeEnvironmentHttpInternalServerError({
+    _tag: "EnvironmentHttpInternalServerError",
+    message: "Legacy environment server failure.",
+  });
+
+  expect(error.operation).toBeUndefined();
+  expect(error.message).toBe("Legacy environment server failure.");
+});
+
 describe("relay request tracing", () => {
   it.effect("does not accept an unauthenticated request trace parent", () =>
     Effect.gen(function* () {
@@ -160,48 +310,127 @@ describe("relay request tracing", () => {
 describe("reconcileDesiredCloudLink", () => {
   it.effect("requires stored CLI authorization without exposing an HTTP endpoint", () =>
     Effect.gen(function* () {
-      const error = yield* Effect.flip(reconcileDesiredCloudLink("http://127.0.0.1:3774"));
+      const error = yield* Effect.flip(
+        reconcileWith({ getExisting: Effect.succeed(Option.none()) }),
+      );
 
       expect(error).toMatchObject({
         _tag: "EnvironmentHttpUnauthorizedError",
+        reason: "cloud_cli_authorization_required",
         message: "Run `t3 connect link` to authorize this environment.",
       });
-    }).pipe(
-      Effect.provideService(
-        ServerSecretStore.ServerSecretStore,
-        makeSecretStore(unusedSecretStoreOperation),
+    }),
+  );
+
+  it.effect("attributes link-proof secret failures to proof generation", () => {
+    const cause = new Error("private secret-store detail");
+    const secretFailure = new ServerSecretStore.SecretStoreReadError({
+      secretName: "environment-key-pair",
+      secretPath: "environment-key-pair.json",
+      cause,
+    });
+    const httpClient = HttpClient.make((request) =>
+      Effect.succeed(
+        HttpClientResponse.fromWeb(
+          request,
+          new Response(
+            JSON.stringify({
+              challenge: "relay-link-challenge",
+              expiresAt: "2099-01-01T00:00:00.000Z",
+            }),
+            { status: 200, headers: { "content-type": "application/json" } },
+          ),
+        ),
       ),
-      Effect.provideService(
-        ServerEnvironment.ServerEnvironment,
-        ServerEnvironment.ServerEnvironment.of({
-          getEnvironmentId: unusedSecretStoreOperation(),
-          getDescriptor: unusedSecretStoreOperation(),
+    );
+    const secretStore = makeSecretStore(unusedSecretStoreOperation);
+
+    return Effect.gen(function* () {
+      const error = yield* Effect.flip(
+        reconcileWith({
+          getExisting: Effect.succeed(
+            Option.some({
+              accessToken: "access-token",
+              refreshToken: "refresh-token",
+              expiresAtEpochMs: Number.MAX_SAFE_INTEGER,
+            }),
+          ),
+          httpClient,
+          secretStore: {
+            ...secretStore,
+            get: () => Effect.fail(secretFailure),
+          },
+          env: { T3CODE_RELAY_URL: "https://relay.example.test" },
         }),
-      ),
-      Effect.provideService(
-        ManagedEndpointRuntime.CloudManagedEndpointRuntime,
-        ManagedEndpointRuntime.CloudManagedEndpointRuntime.of({
-          applyConfig: unusedSecretStoreOperation,
-        } satisfies ManagedEndpointRuntime.CloudManagedEndpointRuntime["Service"]),
-      ),
-      Effect.provideService(
-        EnvironmentAuth.EnvironmentAuth,
-        EnvironmentAuth.EnvironmentAuth.of({} as EnvironmentAuth.EnvironmentAuth["Service"]),
-      ),
-      Effect.provideService(
-        CliTokenManager.CloudCliTokenManager,
-        CliTokenManager.CloudCliTokenManager.of({
-          get: unusedSecretStoreOperation(),
-          getExisting: Effect.succeed(Option.none()),
-          hasCredential: unusedSecretStoreOperation(),
-          clear: unusedSecretStoreOperation(),
+      );
+
+      expect(error).toMatchObject({
+        _tag: "EnvironmentHttpInternalServerError",
+        operation: "generate_link_proof",
+        cause: secretFailure,
+      });
+      expect(error.message).toBe("Could not generate environment link proof.");
+      expect(error.cause).toBe(secretFailure);
+      expect(error.message).not.toContain(cause.message);
+    });
+  });
+
+  it.effect("redacts relay transport failures behind a stable structural message", () => {
+    const transportCause = new Error("upstream included a sensitive database password");
+    const capturedLogs: Array<ReadonlyArray<unknown>> = [];
+    const logger = Logger.make(({ message }) => {
+      capturedLogs.push(Array.isArray(message) ? message : [message]);
+    });
+    const httpClient = HttpClient.make((request) =>
+      Effect.fail(
+        new HttpClientError.HttpClientError({
+          reason: new HttpClientError.TransportError({ request, cause: transportCause }),
         }),
       ),
-      Effect.provideService(
-        HttpClient.HttpClient,
-        HttpClient.make(() => unusedSecretStoreOperation()),
-      ),
-      Effect.provide(NodeServices.layer),
-    ),
-  );
+    );
+
+    return Effect.gen(function* () {
+      const error = yield* Effect.flip(
+        reconcileWith({
+          getExisting: Effect.succeed(
+            Option.some({
+              accessToken: "access-token",
+              refreshToken: "refresh-token",
+              expiresAtEpochMs: Number.MAX_SAFE_INTEGER,
+            }),
+          ),
+          httpClient,
+          env: { T3CODE_RELAY_URL: "https://relay.example.test" },
+        }).pipe(Effect.provide(Logger.layer([logger], { mergeWithExisting: false }))),
+      );
+
+      expect(error).toMatchObject({
+        _tag: "EnvironmentHttpInternalServerError",
+        operation: "relay_request",
+        relayOperation: "create-link-challenge",
+        relayPhase: "send-request",
+        message: "T3 Connect relay create-link-challenge failed during send-request.",
+        cause: {
+          _tag: "CloudRelayRequestError",
+          operation: "create-link-challenge",
+          phase: "send-request",
+        },
+      });
+      expect(error.message).not.toContain(transportCause.message);
+      expect(capturedLogs).toHaveLength(1);
+      const logFields = capturedLogs[0]?.find(
+        (value): value is Record<string, unknown> => typeof value === "object" && value !== null,
+      );
+      expect(logFields).toMatchObject({
+        operation: "relay_request",
+        relayOperation: "create-link-challenge",
+        relayPhase: "send-request",
+        causeTag: "CloudRelayRequestError",
+      });
+      expect(logFields).not.toHaveProperty("cause");
+      expect(capturedLogs[0]?.filter((value) => typeof value === "string").join(" ")).not.toContain(
+        transportCause.message,
+      );
+    });
+  });
 });
diff --git a/apps/server/src/cloud/http.ts b/apps/server/src/cloud/http.ts
index fc2adca9fbc..5effca5340f 100644
--- a/apps/server/src/cloud/http.ts
+++ b/apps/server/src/cloud/http.ts
@@ -9,7 +9,10 @@ import {
   EnvironmentHttpApi,
   EnvironmentHttpBadRequestError,
   EnvironmentHttpConflictError,
+  type EnvironmentHttpInternalOperation,
   EnvironmentHttpInternalServerError,
+  EnvironmentHttpRelayOperation,
+  EnvironmentHttpRelayPhase,
   EnvironmentHttpUnauthorizedError,
 } from "@t3tools/contracts";
 import {
@@ -41,6 +44,7 @@ import {
   verifyRelayJwt,
 } from "@t3tools/shared/relayJwt";
 import { isSecureRelayUrl } from "@t3tools/shared/relayUrl";
+import { getUrlDiagnostics } from "@t3tools/shared/urlDiagnostics";
 import * as DateTime from "effect/DateTime";
 import * as Crypto from "effect/Crypto";
 import * as Duration from "effect/Duration";
@@ -48,8 +52,13 @@ import * as Effect from "effect/Effect";
 import * as Option from "effect/Option";
 import * as Schema from "effect/Schema";
 import * as HttpEffect from "effect/unstable/http/HttpEffect";
-import { HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
-import { HttpClient, HttpClientRequest, HttpClientResponse } from "effect/unstable/http";
+import * as HttpBody from "effect/unstable/http/HttpBody";
+import * as HttpClient from "effect/unstable/http/HttpClient";
+import * as HttpClientError from "effect/unstable/http/HttpClientError";
+import * as HttpClientRequest from "effect/unstable/http/HttpClientRequest";
+import * as HttpClientResponse from "effect/unstable/http/HttpClientResponse";
+import * as HttpServerRequest from "effect/unstable/http/HttpServerRequest";
+import * as HttpServerResponse from "effect/unstable/http/HttpServerResponse";
 import * as HttpApiBuilder from "effect/unstable/httpapi/HttpApiBuilder";
 
 import * as EnvironmentAuth from "../auth/EnvironmentAuth.ts";
@@ -85,26 +94,145 @@ const CLOUD_CREDENTIAL_RESPONSE_HEADERS = {
   pragma: "no-cache",
 } as const;
 
+export class CloudRelayConfigurationError extends Schema.TaggedErrorClass<CloudRelayConfigurationError>()(
+  "CloudRelayConfigurationError",
+  {
+    configKey: Schema.Literal("T3CODE_RELAY_URL"),
+    cause: Schema.Defect(),
+  },
+) {
+  override get message(): string {
+    return `${this.configKey} must be configured as a secure absolute HTTPS origin.`;
+  }
+}
+
+export class CloudRelayRequestError extends Schema.TaggedErrorClass<CloudRelayRequestError>()(
+  "CloudRelayRequestError",
+  {
+    operation: EnvironmentHttpRelayOperation,
+    phase: EnvironmentHttpRelayPhase,
+    method: Schema.Literal("POST"),
+    requestUrlInputLength: Schema.Number,
+    requestUrlProtocol: Schema.optionalKey(Schema.String),
+    requestUrlHostname: Schema.optionalKey(Schema.String),
+    responseStatus: Schema.optional(Schema.Number),
+    cause: Schema.Defect(),
+  },
+) {
+  static fromClientFailure(input: {
+    readonly operation: CloudRelayRequestError["operation"];
+    readonly url: string;
+    readonly cause: HttpBody.HttpBodyError | HttpClientError.HttpClientError | Schema.SchemaError;
+    readonly responseStatus?: number;
+  }): CloudRelayRequestError {
+    const diagnostics = getUrlDiagnostics(input.url);
+    const context = {
+      operation: input.operation,
+      method: "POST" as const,
+      requestUrlInputLength: diagnostics.inputLength,
+      ...(diagnostics.protocol === undefined ? {} : { requestUrlProtocol: diagnostics.protocol }),
+      ...(diagnostics.hostname === undefined ? {} : { requestUrlHostname: diagnostics.hostname }),
+    };
+    if (input.cause._tag === "SchemaError") {
+      return new CloudRelayRequestError({
+        ...context,
+        phase: "decode-response",
+        ...(input.responseStatus === undefined ? {} : { responseStatus: input.responseStatus }),
+        cause: input.cause,
+      });
+    }
+
+    if (!HttpClientError.isHttpClientError(input.cause)) {
+      return new CloudRelayRequestError({
+        ...context,
+        phase: "encode-request",
+        cause: input.cause,
+      });
+    }
+
+    const phase: CloudRelayRequestError["phase"] = (() => {
+      switch (input.cause.reason._tag) {
+        case "EncodeError":
+          return "encode-request";
+        case "TransportError":
+        case "InvalidUrlError":
+          return "send-request";
+        case "StatusCodeError":
+          return "check-response-status";
+        case "DecodeError":
+        case "EmptyBodyError":
+          return "decode-response";
+      }
+    })();
+
+    return new CloudRelayRequestError({
+      ...context,
+      phase,
+      ...(input.cause.response === undefined
+        ? input.responseStatus === undefined
+          ? {}
+          : { responseStatus: input.responseStatus }
+        : { responseStatus: input.cause.response.status }),
+      cause: input.cause,
+    });
+  }
+
+  override get message(): string {
+    const responseStatus =
+      this.responseStatus === undefined ? "" : ` with response status ${this.responseStatus}`;
+    return `T3 Connect relay ${this.operation} failed during ${this.phase}${responseStatus}.`;
+  }
+}
+
 const appendCloudCredentialResponseHeaders = HttpEffect.appendPreResponseHandler(
   (_request, response) =>
     Effect.succeed(HttpServerResponse.setHeaders(response, CLOUD_CREDENTIAL_RESPONSE_HEADERS)),
 );
 
+function errorDiagnosticTag(cause: unknown): string {
+  if (
+    typeof cause === "object" &&
+    cause !== null &&
+    "_tag" in cause &&
+    typeof cause._tag === "string"
+  ) {
+    return cause._tag;
+  }
+  if (cause instanceof Error) return cause.name;
+  return typeof cause;
+}
+
+type EnvironmentCloudInternalErrorContext =
+  | Exclude<EnvironmentHttpInternalOperation, "relay_request">
+  | {
+      readonly operation: "relay_request";
+      readonly relayOperation: CloudRelayRequestError["operation"];
+      readonly relayPhase: CloudRelayRequestError["phase"];
+      readonly responseStatus?: number;
+    };
+
 const failEnvironmentCloudInternalError =
-  (message: string) =>
-  (cause: unknown): Effect.Effect<never, EnvironmentHttpInternalServerError> =>
-    Effect.logError(message, { cause }).pipe(
-      Effect.flatMap(() => Effect.fail(new EnvironmentHttpInternalServerError({ message }))),
+  (context: EnvironmentCloudInternalErrorContext) =>
+  (cause: unknown): Effect.Effect<never, EnvironmentHttpInternalServerError> => {
+    const error =
+      typeof context === "string"
+        ? new EnvironmentHttpInternalServerError({ operation: context, cause })
+        : new EnvironmentHttpInternalServerError({ ...context, cause });
+    const logContext =
+      typeof context === "string"
+        ? { operation: context, causeTag: errorDiagnosticTag(cause) }
+        : { ...context, causeTag: errorDiagnosticTag(cause) };
+    return Effect.logError(error.message, logContext).pipe(
+      Effect.flatMap(() => Effect.fail(error)),
     );
-
-const failCloudCliTokenManagerError = (error: CliTokenManager.CloudCliTokenManagerError) =>
-  failEnvironmentCloudInternalError(error.message)(error);
+  };
 
 const requireRelayUrl = relayUrlConfig.pipe(
   Effect.mapError(
-    () =>
-      new EnvironmentHttpInternalServerError({
-        message: "T3CODE_RELAY_URL must be configured as a secure absolute HTTPS origin.",
+    (cause) =>
+      new CloudRelayConfigurationError({
+        configKey: "T3CODE_RELAY_URL",
+        cause,
       }),
   ),
 );
@@ -126,11 +254,12 @@ export function consumeCloudReplayGuards(input: {
     input.names.map((name) =>
       input.secrets.create(name, input.value).pipe(
         Effect.as(true),
-        Effect.catchIf(ServerSecretStore.isSecretStoreError, (error) =>
-          ServerSecretStore.isSecretAlreadyExistsError(error)
-            ? Effect.succeed(false)
-            : Effect.fail(error),
-        ),
+        Effect.catchTags({
+          SecretStorePersistError: (error) =>
+            ServerSecretStore.isSecretAlreadyExistsError(error)
+              ? Effect.succeed(false)
+              : Effect.fail(error),
+        }),
       ),
     ),
     { concurrency: input.names.length },
@@ -153,9 +282,10 @@ function validateCloudMintPublicKey(
 ): Effect.Effect<void, EnvironmentHttpBadRequestError> {
   return Effect.try({
     try: () => NodeCrypto.createPublicKey(publicKey.replace(/\\n/g, "\n")),
-    catch: () =>
+    catch: (cause) =>
       new EnvironmentHttpBadRequestError({
-        message: "Cloud mint public key must be a valid Ed25519 public key.",
+        reason: "invalid_cloud_mint_public_key",
+        cause,
       }),
   }).pipe(
     Effect.flatMap((key) =>
@@ -163,7 +293,7 @@ function validateCloudMintPublicKey(
         ? Effect.void
         : Effect.fail(
             new EnvironmentHttpBadRequestError({
-              message: "Cloud mint public key must be a valid Ed25519 public key.",
+              reason: "invalid_cloud_mint_public_key",
             }),
           ),
     ),
@@ -176,28 +306,28 @@ function validateRelayConfigPayload(
   if (!isSecureRelayUrl(payload.relayUrl)) {
     return Effect.fail(
       new EnvironmentHttpBadRequestError({
-        message: "Relay URL must be a secure absolute HTTPS URL.",
+        reason: "invalid_relay_url",
       }),
     );
   }
   if (payload.relayIssuer !== undefined && !isSecureRelayUrl(payload.relayIssuer)) {
     return Effect.fail(
       new EnvironmentHttpBadRequestError({
-        message: "Relay issuer must be a secure absolute HTTPS URL.",
+        reason: "invalid_relay_issuer",
       }),
     );
   }
   if (payload.environmentCredential.trim().length === 0) {
     return Effect.fail(
       new EnvironmentHttpBadRequestError({
-        message: "Relay environment credential is required.",
+        reason: "missing_relay_environment_credential",
       }),
     );
   }
   if (payload.cloudUserId.trim().length === 0) {
     return Effect.fail(
       new EnvironmentHttpBadRequestError({
-        message: "Cloud user id is required.",
+        reason: "missing_cloud_user_id",
       }),
     );
   }
@@ -207,7 +337,7 @@ function validateRelayConfigPayload(
 function validateLinkedCloudUser(input: {
   readonly secrets: ServerSecretStore.ServerSecretStore["Service"];
   readonly cloudUserId: string;
-}): Effect.Effect<void, EnvironmentAuth.ServerAuthInternalError | EnvironmentHttpConflictError> {
+}) {
   return input.secrets.get(CLOUD_LINKED_USER_ID).pipe(
     Effect.mapError(
       (cause) =>
@@ -224,17 +354,14 @@ function validateLinkedCloudUser(input: {
         ? Effect.void
         : Effect.fail(
             new EnvironmentHttpConflictError({
-              message:
-                "This environment is already linked to a different cloud account. Unlink it before switching accounts.",
+              reason: "linked_to_different_cloud_account",
             }),
           );
     }),
   );
 }
 
-function readInstalledCloudUserId(
-  secrets: ServerSecretStore.ServerSecretStore["Service"],
-): Effect.Effect<string, EnvironmentAuth.ServerAuthInternalError> {
+function readInstalledCloudUserId(secrets: ServerSecretStore.ServerSecretStore["Service"]) {
   return secrets.get(CLOUD_LINKED_USER_ID).pipe(
     Effect.mapError(
       (cause) =>
@@ -359,7 +486,7 @@ const makeCloudLinkProof = Effect.fn("environment.cloud.makeLinkProof")(function
     })
   ) {
     return yield* new EnvironmentHttpBadRequestError({
-      message: "Invalid managed endpoint origin.",
+      reason: "invalid_managed_endpoint_origin",
     });
   }
   const now = yield* DateTime.now;
@@ -402,24 +529,23 @@ const cloudLinkProofHandler = Effect.fn("environment.cloud.linkProof")(
     const requestUrl = requestAbsoluteUrl(httpRequest);
     if (requestUrl === null || hasForwardedAuthorityHeaders(httpRequest)) {
       return yield* new EnvironmentHttpBadRequestError({
-        message: "Invalid managed endpoint origin.",
+        reason: "invalid_managed_endpoint_origin",
       });
     }
     const proof = yield* makeCloudLinkProof(dependencies, request, requestUrl);
     yield* appendCloudCredentialResponseHeaders;
     return proof satisfies RelayEnvironmentLinkProof;
   },
-  Effect.catchIf(EnvironmentAuth.isServerAuthInternalError, (error) =>
-    failEnvironmentCloudInternalError(error.message)(error),
-  ),
-  Effect.catchIf(
-    ServerSecretStore.isSecretStoreError,
-    failEnvironmentCloudInternalError("Could not generate environment link proof."),
-  ),
-  Effect.catchTag(
-    "PlatformError",
-    failEnvironmentCloudInternalError("Could not generate environment link proof."),
-  ),
+  Effect.catchTags({
+    ServerAuthCloudLinkJwtSigningError: (error) =>
+      failEnvironmentCloudInternalError("sign_cloud_link_jwt")(error),
+    SecretStoreReadError: failEnvironmentCloudInternalError("generate_link_proof"),
+    SecretStoreDecodeError: failEnvironmentCloudInternalError("generate_link_proof"),
+    SecretStoreEncodeError: failEnvironmentCloudInternalError("generate_link_proof"),
+    SecretStorePersistError: failEnvironmentCloudInternalError("generate_link_proof"),
+    SecretStoreConcurrentReadError: failEnvironmentCloudInternalError("generate_link_proof"),
+    PlatformError: failEnvironmentCloudInternalError("generate_link_proof"),
+  }),
 );
 
 const applyCloudRelayConfig = Effect.fn("environment.cloud.applyRelayConfig")(function* (
@@ -439,7 +565,6 @@ const applyCloudRelayConfig = Effect.fn("environment.cloud.applyRelayConfig")(fu
     endpointRuntimeStatus.status === "disabled" || endpointRuntimeStatus.status === "running";
   if (!ok) {
     return yield* new EnvironmentCloudEndpointUnavailableError({
-      message: "Managed endpoint runtime could not be started.",
       endpointRuntimeStatus,
     });
   }
@@ -472,22 +597,22 @@ const cloudRelayConfigHandler = Effect.fn("environment.cloud.relayConfig")(
     yield* requireEnvironmentScope(AuthRelayWriteScope);
     return yield* applyCloudRelayConfig(dependencies, payload);
   },
-  Effect.catchIf(EnvironmentAuth.isServerAuthInternalError, (error) =>
-    failEnvironmentCloudInternalError(error.message)(error),
-  ),
-  Effect.catchIf(
-    ServerSecretStore.isSecretStoreError,
-    failEnvironmentCloudInternalError("Could not persist environment relay configuration."),
-  ),
-  Effect.catchTag(
-    "SchemaError",
-    failEnvironmentCloudInternalError("Could not persist environment relay configuration."),
-  ),
+  Effect.catchTags({
+    ServerAuthLinkedCloudAccountVerificationError: (error) =>
+      failEnvironmentCloudInternalError("verify_linked_cloud_account")(error),
+    SecretStoreTemporaryPathGenerationError: failEnvironmentCloudInternalError(
+      "persist_relay_configuration",
+    ),
+    SecretStorePersistError: failEnvironmentCloudInternalError("persist_relay_configuration"),
+    SecretStoreRemoveError: failEnvironmentCloudInternalError("persist_relay_configuration"),
+    SchemaError: failEnvironmentCloudInternalError("persist_relay_configuration"),
+  }),
 );
 
 const relayClientRequest = <A>(
   dependencies: CloudHttpDependencies,
   input: {
+    readonly operation: CloudRelayRequestError["operation"];
     readonly url: string;
     readonly token: string;
     readonly payload: unknown;
@@ -497,14 +622,46 @@ const relayClientRequest = <A>(
   HttpClientRequest.post(input.url).pipe(
     HttpClientRequest.bearerToken(input.token),
     HttpClientRequest.bodyJson(input.payload),
-    Effect.flatMap(dependencies.httpClient.execute),
-    Effect.flatMap(HttpClientResponse.filterStatusOk),
-    Effect.flatMap(HttpClientResponse.schemaBodyJson(input.schema)),
-    Effect.mapError(
-      (cause) =>
-        new EnvironmentHttpInternalServerError({
-          message: `T3 Connect relay request failed: ${String(cause)}`,
-        }),
+    Effect.mapError((cause) =>
+      CloudRelayRequestError.fromClientFailure({
+        operation: input.operation,
+        url: input.url,
+        cause,
+      }),
+    ),
+    Effect.flatMap((request) =>
+      dependencies.httpClient.execute(request).pipe(
+        Effect.mapError((cause) =>
+          CloudRelayRequestError.fromClientFailure({
+            operation: input.operation,
+            url: input.url,
+            cause,
+          }),
+        ),
+      ),
+    ),
+    Effect.flatMap((response) =>
+      HttpClientResponse.filterStatusOk(response).pipe(
+        Effect.mapError((cause) =>
+          CloudRelayRequestError.fromClientFailure({
+            operation: input.operation,
+            url: input.url,
+            cause,
+          }),
+        ),
+      ),
+    ),
+    Effect.flatMap((response) =>
+      HttpClientResponse.schemaBodyJson(input.schema)(response).pipe(
+        Effect.mapError((cause) =>
+          CloudRelayRequestError.fromClientFailure({
+            operation: input.operation,
+            url: input.url,
+            responseStatus: response.status,
+            cause,
+          }),
+        ),
+      ),
     ),
     withRelayClientTracing,
   );
@@ -513,14 +670,15 @@ const reconcileDesiredCloudLinkWith = Effect.fn("environment.cloud.reconcileDesi
   function* (dependencies: CloudHttpDependencies, localOrigin: string) {
     const localUrl = yield* Effect.try({
       try: () => new URL(localOrigin),
-      catch: () =>
+      catch: (cause) =>
         new EnvironmentHttpBadRequestError({
-          message: "Could not resolve local environment origin.",
+          reason: "invalid_local_environment_origin",
+          cause,
         }),
     });
     if (localUrl.origin !== localOrigin) {
       return yield* new EnvironmentHttpBadRequestError({
-        message: "Could not resolve local environment origin.",
+        reason: "invalid_local_environment_origin",
       });
     }
     const localWsOrigin = localOrigin.replace(/^http/u, "ws");
@@ -530,7 +688,7 @@ const reconcileDesiredCloudLinkWith = Effect.fn("environment.cloud.reconcileDesi
           onNone: () =>
             Effect.fail(
               new EnvironmentHttpUnauthorizedError({
-                message: "Run `t3 connect link` to authorize this environment.",
+                reason: "cloud_cli_authorization_required",
               }),
             ),
           onSome: Effect.succeed,
@@ -539,6 +697,7 @@ const reconcileDesiredCloudLinkWith = Effect.fn("environment.cloud.reconcileDesi
     );
     const relayUrl = yield* requireRelayUrl;
     const challenge = yield* relayClientRequest(dependencies, {
+      operation: "create-link-challenge",
       url: `${relayUrl}/v1/client/environment-link-challenges`,
       token: token.accessToken,
       payload: {
@@ -564,8 +723,20 @@ const reconcileDesiredCloudLinkWith = Effect.fn("environment.cloud.reconcileDesi
         },
       },
       localOrigin,
+    ).pipe(
+      Effect.catchTags({
+        ServerAuthCloudLinkJwtSigningError: (error) =>
+          failEnvironmentCloudInternalError("sign_cloud_link_jwt")(error),
+        SecretStoreReadError: failEnvironmentCloudInternalError("generate_link_proof"),
+        SecretStoreDecodeError: failEnvironmentCloudInternalError("generate_link_proof"),
+        SecretStoreEncodeError: failEnvironmentCloudInternalError("generate_link_proof"),
+        SecretStorePersistError: failEnvironmentCloudInternalError("generate_link_proof"),
+        SecretStoreConcurrentReadError: failEnvironmentCloudInternalError("generate_link_proof"),
+        PlatformError: failEnvironmentCloudInternalError("generate_link_proof"),
+      }),
     );
     const link = yield* relayClientRequest(dependencies, {
+      operation: "create-environment-link",
       url: `${relayUrl}/v1/client/environment-links`,
       token: token.accessToken,
       payload: {
@@ -576,7 +747,15 @@ const reconcileDesiredCloudLinkWith = Effect.fn("environment.cloud.reconcileDesi
       },
       schema: RelayEnvironmentLinkResponse,
     });
-    yield* setCliDesiredCloudLink(true);
+    yield* setCliDesiredCloudLink(true).pipe(
+      Effect.catchTags({
+        SecretStoreTemporaryPathGenerationError: failEnvironmentCloudInternalError(
+          "persist_desired_link_state",
+        ),
+        SecretStorePersistError: failEnvironmentCloudInternalError("persist_desired_link_state"),
+        SecretStoreRemoveError: failEnvironmentCloudInternalError("persist_desired_link_state"),
+      }),
+    );
     return yield* applyCloudRelayConfig(dependencies, {
       relayUrl,
       relayIssuer: link.relayIssuer,
@@ -584,18 +763,31 @@ const reconcileDesiredCloudLinkWith = Effect.fn("environment.cloud.reconcileDesi
       environmentCredential: link.environmentCredential,
       cloudMintPublicKey: link.cloudMintPublicKey,
       endpointRuntime: link.endpointRuntime,
-    });
+    }).pipe(
+      Effect.catchTags({
+        ServerAuthLinkedCloudAccountVerificationError: (error) =>
+          failEnvironmentCloudInternalError("verify_linked_cloud_account")(error),
+        SecretStoreTemporaryPathGenerationError: failEnvironmentCloudInternalError(
+          "persist_relay_configuration",
+        ),
+        SecretStorePersistError: failEnvironmentCloudInternalError("persist_relay_configuration"),
+        SecretStoreRemoveError: failEnvironmentCloudInternalError("persist_relay_configuration"),
+        SchemaError: failEnvironmentCloudInternalError("persist_relay_configuration"),
+      }),
+    );
   },
-  Effect.catchIf(
-    ServerSecretStore.isSecretStoreError,
-    failEnvironmentCloudInternalError("Could not persist desired T3 Connect link state."),
-  ),
   Effect.catchTags({
-    CloudCliCredentialRemovalError: failCloudCliTokenManagerError,
-    CloudCliCredentialRefreshError: failCloudCliTokenManagerError,
-    CloudCliCredentialReadError: failCloudCliTokenManagerError,
-    CloudCliAuthorizationError: failCloudCliTokenManagerError,
-    CloudCliAuthorizationTimeoutError: failCloudCliTokenManagerError,
+    CloudRelayConfigurationError: (error) =>
+      failEnvironmentCloudInternalError("read_relay_url_configuration")(error),
+    CloudRelayRequestError: (error) =>
+      failEnvironmentCloudInternalError({
+        operation: "relay_request",
+        relayOperation: error.operation,
+        relayPhase: error.phase,
+        ...(error.responseStatus === undefined ? {} : { responseStatus: error.responseStatus }),
+      })(error),
+    CloudCliCredentialRefreshError: (error) =>
+      failEnvironmentCloudInternalError("refresh_cloud_cli_credential")(error),
   }),
 );
 
@@ -633,10 +825,9 @@ const cloudLinkStateHandler = Effect.fn("environment.cloud.linkState")(
     yield* requireEnvironmentScope(AuthRelayReadScope);
     return yield* readCloudLinkState(dependencies);
   },
-  Effect.catchIf(
-    ServerSecretStore.isSecretStoreError,
-    failEnvironmentCloudInternalError("Could not read environment relay configuration."),
-  ),
+  Effect.catchTags({
+    SecretStoreReadError: failEnvironmentCloudInternalError("read_relay_configuration"),
+  }),
 );
 
 const cloudUnlinkHandler = Effect.fn("environment.cloud.unlink")(
@@ -658,10 +849,13 @@ const cloudUnlinkHandler = Effect.fn("environment.cloud.unlink")(
     yield* setCliDesiredCloudLink(false);
     return { ok: true, endpointRuntimeStatus } satisfies EnvironmentCloudRelayConfigResult;
   },
-  Effect.catchIf(
-    ServerSecretStore.isSecretStoreError,
-    failEnvironmentCloudInternalError("Could not remove environment relay configuration."),
-  ),
+  Effect.catchTags({
+    SecretStoreTemporaryPathGenerationError: failEnvironmentCloudInternalError(
+      "remove_relay_configuration",
+    ),
+    SecretStorePersistError: failEnvironmentCloudInternalError("remove_relay_configuration"),
+    SecretStoreRemoveError: failEnvironmentCloudInternalError("remove_relay_configuration"),
+  }),
 );
 
 const cloudPreferencesHandler = Effect.fn("environment.cloud.preferences")(
@@ -676,10 +870,13 @@ const cloudPreferencesHandler = Effect.fn("environment.cloud.preferences")(
     );
     return yield* readCloudLinkState(dependencies);
   },
-  Effect.catchIf(
-    ServerSecretStore.isSecretStoreError,
-    failEnvironmentCloudInternalError("Could not persist environment cloud preferences."),
-  ),
+  Effect.catchTags({
+    SecretStoreReadError: failEnvironmentCloudInternalError("persist_cloud_preferences"),
+    SecretStoreTemporaryPathGenerationError: failEnvironmentCloudInternalError(
+      "persist_cloud_preferences",
+    ),
+    SecretStorePersistError: failEnvironmentCloudInternalError("persist_cloud_preferences"),
+  }),
 );
 
 const cloudEnvironmentHealthHandler = Effect.fn("environment.cloud.health")(
@@ -730,7 +927,7 @@ const cloudEnvironmentHealthHandler = Effect.fn("environment.cloud.health")(
       !hasExactScope({ scopes: proofOption.value.scope, expected: "environment:status" })
     ) {
       return yield* new EnvironmentHttpUnauthorizedError({
-        message: "Invalid cloud health request.",
+        reason: "invalid_cloud_health_request",
       });
     }
     const proof = proofOption.value;
@@ -744,7 +941,7 @@ const cloudEnvironmentHealthHandler = Effect.fn("environment.cloud.health")(
     });
     if (!consumedReplayGuards) {
       return yield* new EnvironmentHttpConflictError({
-        message: "Cloud health request was already consumed.",
+        reason: "cloud_health_request_replayed",
       });
     }
 
@@ -787,17 +984,26 @@ const cloudEnvironmentHealthHandler = Effect.fn("environment.cloud.health")(
     yield* appendCloudCredentialResponseHeaders;
     return response;
   },
-  Effect.catchIf(EnvironmentAuth.isServerAuthInternalError, (error) =>
-    failEnvironmentCloudInternalError(error.message)(error),
-  ),
-  Effect.catchIf(
-    ServerSecretStore.isSecretStoreError,
-    failEnvironmentCloudInternalError("Could not answer cloud health request."),
-  ),
-  Effect.catchTag(
-    "PlatformError",
-    failEnvironmentCloudInternalError("Could not answer cloud health request."),
-  ),
+  Effect.catchTags({
+    ServerAuthLinkedCloudAccountReadError: (error) =>
+      failEnvironmentCloudInternalError("read_linked_cloud_account")(error),
+    ServerAuthLinkedCloudAccountMissingError: (error) =>
+      failEnvironmentCloudInternalError("require_linked_cloud_account")(error),
+    ServerAuthCloudMintPublicKeyMissingError: (error) =>
+      failEnvironmentCloudInternalError("read_cloud_mint_public_key")(error),
+    ServerAuthCloudRelayIssuerMissingError: (error) =>
+      failEnvironmentCloudInternalError("read_cloud_relay_issuer")(error),
+    ServerAuthCloudHealthJwtSigningError: (error) =>
+      failEnvironmentCloudInternalError("sign_cloud_health_jwt")(error),
+    SecretStoreReadError: failEnvironmentCloudInternalError("answer_cloud_health_request"),
+    SecretStorePersistError: failEnvironmentCloudInternalError("answer_cloud_health_request"),
+    SecretStoreDecodeError: failEnvironmentCloudInternalError("answer_cloud_health_request"),
+    SecretStoreEncodeError: failEnvironmentCloudInternalError("answer_cloud_health_request"),
+    SecretStoreConcurrentReadError: failEnvironmentCloudInternalError(
+      "answer_cloud_health_request",
+    ),
+    PlatformError: failEnvironmentCloudInternalError("answer_cloud_health_request"),
+  }),
 );
 
 const cloudMintCredentialHandler = Effect.fn("environment.cloud.mintCredential")(
@@ -849,7 +1055,7 @@ const cloudMintCredentialHandler = Effect.fn("environment.cloud.mintCredential")
       !hasExactScope({ scopes: proofOption.value.scope, expected: "environment:connect" })
     ) {
       return yield* new EnvironmentHttpUnauthorizedError({
-        message: "Invalid cloud mint request.",
+        reason: "invalid_cloud_mint_request",
       });
     }
     const proof = proofOption.value;
@@ -863,7 +1069,7 @@ const cloudMintCredentialHandler = Effect.fn("environment.cloud.mintCredential")
     });
     if (!consumedReplayGuards) {
       return yield* new EnvironmentHttpConflictError({
-        message: "Cloud mint request was already consumed.",
+        reason: "cloud_mint_request_replayed",
       });
     }
 
@@ -908,17 +1114,28 @@ const cloudMintCredentialHandler = Effect.fn("environment.cloud.mintCredential")
     yield* appendCloudCredentialResponseHeaders;
     return response;
   },
-  Effect.catchIf(EnvironmentAuth.isServerAuthInternalError, (error) =>
-    failEnvironmentCloudInternalError(error.message)(error),
-  ),
-  Effect.catchIf(
-    ServerSecretStore.isSecretStoreError,
-    failEnvironmentCloudInternalError("Could not issue cloud connection credential."),
-  ),
-  Effect.catchTag(
-    "PlatformError",
-    failEnvironmentCloudInternalError("Could not issue cloud connection credential."),
-  ),
+  Effect.catchTags({
+    ServerAuthLinkedCloudAccountReadError: (error) =>
+      failEnvironmentCloudInternalError("read_linked_cloud_account")(error),
+    ServerAuthLinkedCloudAccountMissingError: (error) =>
+      failEnvironmentCloudInternalError("require_linked_cloud_account")(error),
+    ServerAuthCloudMintPublicKeyMissingError: (error) =>
+      failEnvironmentCloudInternalError("read_cloud_mint_public_key")(error),
+    ServerAuthCloudRelayIssuerMissingError: (error) =>
+      failEnvironmentCloudInternalError("read_cloud_relay_issuer")(error),
+    ServerAuthPairingLinkCreationError: (error) =>
+      failEnvironmentCloudInternalError("create_cloud_pairing_link")(error),
+    ServerAuthCloudMintJwtSigningError: (error) =>
+      failEnvironmentCloudInternalError("sign_cloud_mint_jwt")(error),
+    SecretStoreReadError: failEnvironmentCloudInternalError("issue_cloud_connection_credential"),
+    SecretStorePersistError: failEnvironmentCloudInternalError("issue_cloud_connection_credential"),
+    SecretStoreDecodeError: failEnvironmentCloudInternalError("issue_cloud_connection_credential"),
+    SecretStoreEncodeError: failEnvironmentCloudInternalError("issue_cloud_connection_credential"),
+    SecretStoreConcurrentReadError: failEnvironmentCloudInternalError(
+      "issue_cloud_connection_credential",
+    ),
+    PlatformError: failEnvironmentCloudInternalError("issue_cloud_connection_credential"),
+  }),
 );
 
 export const connectHttpApiLayer = HttpApiBuilder.group(
diff --git a/apps/server/src/http.test.ts b/apps/server/src/http.test.ts
index a1d4230e75c..0e1f56c8e53 100644
--- a/apps/server/src/http.test.ts
+++ b/apps/server/src/http.test.ts
@@ -1,6 +1,12 @@
 import { describe, expect, it } from "vite-plus/test";
 
-import { isLoopbackHostname, resolveDevRedirectUrl } from "./http.ts";
+import {
+  BrowserOtlpTraceCollectionError,
+  BrowserOtlpTraceDecodeError,
+  BrowserOtlpTraceExportError,
+  isLoopbackHostname,
+  resolveDevRedirectUrl,
+} from "./http.ts";
 
 describe("http dev routing", () => {
   it("treats localhost and loopback addresses as local", () => {
@@ -25,3 +31,73 @@ describe("http dev routing", () => {
     );
   });
 });
+
+describe("browser OTLP diagnostics", () => {
+  it("retains decode causes without retaining the trace payload", () => {
+    const cause = new Error("private trace payload detail");
+    const error = BrowserOtlpTraceDecodeError.fromPayload({ resourceSpans: [] }, cause);
+
+    expect(error).toMatchObject({
+      resourceSpanCount: 0,
+      cause,
+      message: "Failed to decode browser OTLP payload with 0 resource spans.",
+    });
+    expect(error.cause).toBe(cause);
+    expect(error).not.toHaveProperty("bodyJson");
+  });
+
+  it("describes malformed trace payloads without inspecting unsafe fields", () => {
+    const cause = new Error("private malformed trace payload detail");
+    const error = BrowserOtlpTraceDecodeError.fromPayload(
+      { resourceSpans: "private malformed resource spans" },
+      cause,
+    );
+
+    expect(error).toMatchObject({
+      resourceSpanCount: 0,
+      cause,
+      message: "Failed to decode browser OTLP payload with 0 resource spans.",
+    });
+    expect(error.cause).toBe(cause);
+    expect(error).not.toHaveProperty("resourceSpans");
+  });
+
+  it("retains local collection causes with a structural record count", () => {
+    const records = [{ type: "private trace record" }];
+    const cause = new Error("private local collector detail");
+    const error = BrowserOtlpTraceCollectionError.fromRecords(records, cause);
+
+    expect(error).toMatchObject({
+      recordCount: 1,
+      cause,
+      message: "Failed to collect 1 browser OTLP trace records locally.",
+    });
+    expect(error.cause).toBe(cause);
+    expect(error).not.toHaveProperty("records");
+  });
+
+  it("redacts collector URL credentials while retaining the exact cause", () => {
+    const collectorUrl =
+      "https://collector-user:collector-password@traces.example.test/private/v1/traces?access_token=collector-secret#collector-fragment";
+    const cause = new Error("collector transport failed");
+    const error = BrowserOtlpTraceExportError.fromCollectorUrl(collectorUrl, cause);
+
+    expect(error).toMatchObject({
+      collectorUrlInputLength: collectorUrl.length,
+      collectorUrlProtocol: "https:",
+      collectorUrlHostname: "traces.example.test",
+      cause,
+    });
+    expect(error.cause).toBe(cause);
+    expect(error).not.toHaveProperty("collectorUrl");
+    for (const secret of [
+      "collector-user",
+      "collector-password",
+      "/private/v1/traces",
+      "collector-secret",
+      "collector-fragment",
+    ]) {
+      expect(error.message).not.toContain(secret);
+    }
+  });
+});
diff --git a/apps/server/src/http.ts b/apps/server/src/http.ts
index ce9b498cb1f..d7e88d62d1e 100644
--- a/apps/server/src/http.ts
+++ b/apps/server/src/http.ts
@@ -5,12 +5,13 @@ import {
   EnvironmentHttpApi,
 } from "@t3tools/contracts";
 import { decodeOtlpTraceRecords } from "@t3tools/shared/observability";
-import * as Data from "effect/Data";
+import { getUrlDiagnostics } from "@t3tools/shared/urlDiagnostics";
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
 import * as Layer from "effect/Layer";
 import * as Option from "effect/Option";
 import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
 import { cast } from "effect/Function";
 import {
   HttpBody,
@@ -35,9 +36,8 @@ import * as EnvironmentAuth from "./auth/EnvironmentAuth.ts";
 import { traceRelayRequest } from "./cloud/traceRelayRequest.ts";
 import {
   annotateEnvironmentRequest,
+  catchEnvironmentAuthenticationErrors,
   failEnvironmentScopeRequired,
-  failEnvironmentAuthInvalid,
-  failEnvironmentInternal,
 } from "./auth/http.ts";
 import * as ServerEnvironment from "./environment/ServerEnvironment.ts";
 import { browserApiCorsAllowedHeaders, browserApiCorsAllowedMethods } from "./httpCors.ts";
@@ -80,13 +80,8 @@ const authenticateRawRouteWithScope = (
   Effect.gen(function* () {
     const request = yield* HttpServerRequest.HttpServerRequest;
     const serverAuth = yield* EnvironmentAuth.EnvironmentAuth;
-    const session = yield* serverAuth.authenticateHttpRequest(request).pipe(
-      Effect.catchIf(EnvironmentAuth.isServerAuthCredentialError, (error) =>
-        failEnvironmentAuthInvalid(EnvironmentAuth.serverAuthCredentialReason(error)),
-      ),
-      Effect.catchIf(EnvironmentAuth.isServerAuthInternalError, (error) =>
-        failEnvironmentInternal("internal_error", error),
-      ),
+    const session = yield* catchEnvironmentAuthenticationErrors(
+      serverAuth.authenticateHttpRequest(request),
     );
     if (!session.scopes.includes(scope)) {
       return yield* failEnvironmentScopeRequired(scope);
@@ -108,10 +103,95 @@ export const serverEnvironmentHttpApiLayer = HttpApiBuilder.group(
   }),
 );
 
-class DecodeOtlpTraceRecordsError extends Data.TaggedError("DecodeOtlpTraceRecordsError")<{
-  readonly cause: unknown;
-  readonly bodyJson: OtlpTracer.TraceData;
-}> {}
+function errorDiagnosticTag(cause: unknown): string {
+  if (
+    typeof cause === "object" &&
+    cause !== null &&
+    "_tag" in cause &&
+    typeof cause._tag === "string"
+  ) {
+    return cause._tag;
+  }
+  if (cause instanceof Error) return cause.name;
+  return typeof cause;
+}
+
+export class BrowserOtlpTraceDecodeError extends Schema.TaggedErrorClass<BrowserOtlpTraceDecodeError>()(
+  "BrowserOtlpTraceDecodeError",
+  {
+    resourceSpanCount: Schema.Number,
+    cause: Schema.Defect(),
+  },
+) {
+  static fromPayload(payload: unknown, cause: unknown): BrowserOtlpTraceDecodeError {
+    const resourceSpanCount =
+      typeof payload === "object" &&
+      payload !== null &&
+      "resourceSpans" in payload &&
+      Array.isArray(payload.resourceSpans)
+        ? payload.resourceSpans.length
+        : 0;
+
+    return new BrowserOtlpTraceDecodeError({
+      resourceSpanCount,
+      cause,
+    });
+  }
+
+  override get message(): string {
+    return `Failed to decode browser OTLP payload with ${this.resourceSpanCount} resource spans.`;
+  }
+}
+
+export class BrowserOtlpTraceCollectionError extends Schema.TaggedErrorClass<BrowserOtlpTraceCollectionError>()(
+  "BrowserOtlpTraceCollectionError",
+  {
+    recordCount: Schema.Number,
+    cause: Schema.Defect(),
+  },
+) {
+  static fromRecords(
+    records: ReadonlyArray<unknown>,
+    cause: unknown,
+  ): BrowserOtlpTraceCollectionError {
+    return new BrowserOtlpTraceCollectionError({
+      recordCount: records.length,
+      cause,
+    });
+  }
+
+  override get message(): string {
+    return `Failed to collect ${this.recordCount} browser OTLP trace records locally.`;
+  }
+}
+
+export class BrowserOtlpTraceExportError extends Schema.TaggedErrorClass<BrowserOtlpTraceExportError>()(
+  "BrowserOtlpTraceExportError",
+  {
+    collectorUrlInputLength: Schema.Number,
+    collectorUrlProtocol: Schema.optionalKey(Schema.String),
+    collectorUrlHostname: Schema.optionalKey(Schema.String),
+    cause: Schema.Defect(),
+  },
+) {
+  static fromCollectorUrl(collectorUrl: string, cause: unknown): BrowserOtlpTraceExportError {
+    const diagnostics = getUrlDiagnostics(collectorUrl);
+    return new BrowserOtlpTraceExportError({
+      collectorUrlInputLength: diagnostics.inputLength,
+      ...(diagnostics.protocol === undefined ? {} : { collectorUrlProtocol: diagnostics.protocol }),
+      ...(diagnostics.hostname === undefined ? {} : { collectorUrlHostname: diagnostics.hostname }),
+      cause,
+    });
+  }
+
+  override get message(): string {
+    const collector =
+      this.collectorUrlHostname === undefined
+        ? "the configured collector"
+        : this.collectorUrlHostname;
+    return `Failed to export browser OTLP traces to ${collector} (collector URL input length ${this.collectorUrlInputLength}).`;
+  }
+}
 
 export const otlpTracesProxyRouteLayer = HttpRouter.add(
   "POST",
@@ -127,15 +207,31 @@ export const otlpTracesProxyRouteLayer = HttpRouter.add(
 
     yield* Effect.try({
       try: () => decodeOtlpTraceRecords(bodyJson),
-      catch: (cause) => new DecodeOtlpTraceRecordsError({ cause, bodyJson }),
+      catch: (cause) => BrowserOtlpTraceDecodeError.fromPayload(bodyJson, cause),
     }).pipe(
-      Effect.flatMap((records) => browserTraceCollector.record(records)),
-      Effect.catch((cause) =>
-        Effect.logWarning("Failed to decode browser OTLP traces", {
-          cause,
-          bodyJson,
-        }),
+      Effect.flatMap((records) =>
+        browserTraceCollector
+          .record(records)
+          .pipe(
+            Effect.catchDefect((cause) =>
+              Effect.fail(BrowserOtlpTraceCollectionError.fromRecords(records, cause)),
+            ),
+          ),
       ),
+      Effect.catchTags({
+        BrowserOtlpTraceDecodeError: (error) =>
+          Effect.logWarning(error.message, {
+            errorTag: error._tag,
+            resourceSpanCount: error.resourceSpanCount,
+            causeTag: errorDiagnosticTag(error.cause),
+          }),
+        BrowserOtlpTraceCollectionError: (error) =>
+          Effect.logWarning(error.message, {
+            errorTag: error._tag,
+            recordCount: error.recordCount,
+            causeTag: errorDiagnosticTag(error.cause),
+          }),
+      }),
     );
 
     if (otlpTracesUrl === undefined) {
@@ -149,15 +245,23 @@ export const otlpTracesProxyRouteLayer = HttpRouter.add(
       .pipe(
         Effect.flatMap(HttpClientResponse.filterStatusOk),
         Effect.as(HttpServerResponse.empty({ status: 204 })),
-        Effect.tapError((cause) =>
-          Effect.logWarning("Failed to export browser OTLP traces", {
-            cause,
-            otlpTracesUrl,
-          }),
-        ),
-        Effect.orElseSucceed(() =>
-          HttpServerResponse.text("Trace export failed.", { status: 502 }),
+        Effect.mapError((cause) =>
+          BrowserOtlpTraceExportError.fromCollectorUrl(otlpTracesUrl, cause),
         ),
+        Effect.catchTags({
+          BrowserOtlpTraceExportError: (error) =>
+            Effect.logWarning(error.message, {
+              errorTag: error._tag,
+              collectorUrlInputLength: error.collectorUrlInputLength,
+              ...(error.collectorUrlProtocol === undefined
+                ? {}
+                : { collectorUrlProtocol: error.collectorUrlProtocol }),
+              ...(error.collectorUrlHostname === undefined
+                ? {}
+                : { collectorUrlHostname: error.collectorUrlHostname }),
+              causeTag: errorDiagnosticTag(error.cause),
+            }).pipe(Effect.as(HttpServerResponse.text("Trace export failed.", { status: 502 }))),
+        }),
       );
   }).pipe(
     Effect.catchTags({
diff --git a/apps/server/src/keybindings.test.ts b/apps/server/src/keybindings.test.ts
index ba95422735c..9884552a05f 100644
--- a/apps/server/src/keybindings.test.ts
+++ b/apps/server/src/keybindings.test.ts
@@ -1,17 +1,16 @@
 import { KeybindingCommand, KeybindingRule, KeybindingsConfig } from "@t3tools/contracts";
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { assert, it } from "@effect/vitest";
-import { assertFailure } from "@effect/vitest/utils";
 import * as Cause from "effect/Cause";
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
 import * as Layer from "effect/Layer";
 import * as Logger from "effect/Logger";
 import * as Path from "effect/Path";
+import * as Result from "effect/Result";
 import * as Schema from "effect/Schema";
 import * as ServerConfig from "./config.ts";
 import * as Keybindings from "./keybindings.ts";
-import { KeybindingsConfigError } from "@t3tools/contracts";
 
 const KeybindingsConfigJson = Schema.fromJsonString(KeybindingsConfig);
 const encodeKeybindingsConfigJson = Schema.encodeEffect(KeybindingsConfigJson);
@@ -34,12 +33,6 @@ const makeKeybindingsLayer = () => {
   );
 };
 
-const toDetailResult = <A, R>(effect: Effect.Effect<A, KeybindingsConfigError, R>) =>
-  effect.pipe(
-    Effect.mapError((error) => error.detail),
-    Effect.result,
-  );
-
 const writeKeybindingsConfig = (configPath: string, rules: readonly KeybindingRule[]) =>
   Effect.gen(function* () {
     const fileSystem = yield* FileSystem.FileSystem;
@@ -223,15 +216,21 @@ it.layer(NodeServices.layer)("keybindings", (it) => {
       assert.deepEqual(configState.issues, [
         {
           kind: "keybindings.malformed-config",
-          message: configState.issues[0]?.message ?? "",
+          message: "Expected the keybindings configuration to be a JSON array.",
         },
       ]);
       assert.equal(yield* fs.readFileString(keybindingsConfigPath), "{ not-json");
     }).pipe(Effect.provide(makeKeybindingsLayer())),
   );
 
-  it.effect("ignores invalid entries in runtime and reports them as issues", () =>
-    Effect.gen(function* () {
+  it.effect("ignores invalid entries in runtime and reports them as issues", () => {
+    const logs: ReadonlyArray<unknown>[] = [];
+    const logger = Logger.make(({ message }) => {
+      logs.push(Array.isArray(message) ? message : [message]);
+    });
+    const secret = "private-shortcut-payload";
+
+    return Effect.gen(function* () {
       const fs = yield* FileSystem.FileSystem;
       const { keybindingsConfigPath } = yield* ServerConfig.ServerConfig;
       yield* fs.writeFileString(
@@ -240,7 +239,7 @@ it.layer(NodeServices.layer)("keybindings", (it) => {
         JSON.stringify([
           { key: "mod+j", command: "terminal.toggle" },
           { key: "mod+shift+d+o", command: "terminal.new" },
-          { key: "mod+x", command: "invalid.command" },
+          { key: "mod+x", command: secret },
         ]),
       );
 
@@ -250,23 +249,55 @@ it.layer(NodeServices.layer)("keybindings", (it) => {
       });
 
       assert.isTrue(configState.keybindings.some((entry) => entry.command === "terminal.toggle"));
-      assert.isFalse(
-        configState.keybindings.some((entry) => String(entry.command) === "invalid.command"),
-      );
+      assert.isFalse(configState.keybindings.some((entry) => String(entry.command) === secret));
       assert.deepEqual(configState.issues, [
         {
           kind: "keybindings.invalid-entry",
           index: 1,
-          message: configState.issues[0]?.message ?? "",
+          message: "The keybinding entry contains an invalid shortcut or when expression.",
         },
         {
           kind: "keybindings.invalid-entry",
           index: 2,
-          message: configState.issues[1]?.message ?? "",
+          message: "Expected a keybinding entry with key, command, and optional when fields.",
         },
       ]);
-    }).pipe(Effect.provide(makeKeybindingsLayer())),
-  );
+      const invalidEntryLog = logs.find((log) => {
+        const attributes = log[1];
+        return (
+          String(log[0]).includes("ignoring invalid keybinding entry") &&
+          typeof attributes === "object" &&
+          attributes !== null &&
+          Reflect.get(attributes, "entryIndex") === 2
+        );
+      });
+      if (!invalidEntryLog) {
+        return assert.fail("Expected invalid keybinding warning");
+      }
+      const attributes = invalidEntryLog[1];
+      if (typeof attributes !== "object" || attributes === null) {
+        return assert.fail("Expected structured invalid keybinding attributes");
+      }
+      assert.equal(Reflect.get(attributes, "validationStage"), "entry-schema");
+      assert.equal(Reflect.get(attributes, "validationInputKind"), "object");
+      assert.equal(Reflect.get(attributes, "validationInputSize"), 2);
+      assert.equal(Reflect.get(attributes, "validationHasKeyField"), true);
+      assert.equal(Reflect.get(attributes, "validationHasCommandField"), true);
+      assert.equal(Reflect.get(attributes, "validationHasWhenField"), false);
+      assert.equal(Reflect.get(attributes, "causeReasonCount"), 1);
+      assert.isFalse("entry" in attributes);
+      assert.isFalse("cause" in attributes);
+      assert.isFalse(String(invalidEntryLog[0]).includes(secret));
+      assert.isFalse(Object.values(attributes).some((value) => String(value).includes(secret)));
+    }).pipe(
+      Effect.provide(
+        Layer.mergeAll(
+          makeKeybindingsLayer(),
+          Logger.layer([logger], { mergeWithExisting: false }),
+        ),
+      ),
+    );
+  });
 
   it.effect(
     "upserts missing default keybindings on startup without overriding existing command rules",
@@ -301,9 +332,9 @@ it.layer(NodeServices.layer)("keybindings", (it) => {
   );
 
   it.effect("skips conflicting default keybindings on startup and logs a detailed warning", () => {
-    const messages: string[] = [];
+    const logs: ReadonlyArray<unknown>[] = [];
     const logger = Logger.make(({ message }) => {
-      messages.push(String(message));
+      logs.push(Array.isArray(message) ? message : [message]);
     });
 
     return Effect.gen(function* () {
@@ -321,11 +352,21 @@ it.layer(NodeServices.layer)("keybindings", (it) => {
       assert.isFalse(persisted.some((entry) => entry.command === "terminal.toggle"));
       assert.isTrue(persisted.some((entry) => entry.command === "script.custom-action.run"));
 
-      assert.isTrue(
-        messages.some((message) =>
-          message.includes("skipping default keybinding due to shortcut conflict"),
-        ),
+      const warning = logs.find((log) =>
+        String(log[0]).includes("skipping default keybinding due to shortcut conflict"),
       );
+      if (!warning) {
+        return assert.fail("Expected shortcut conflict warning");
+      }
+      const attributes = warning[1];
+      if (typeof attributes !== "object" || attributes === null) {
+        return assert.fail("Expected structured shortcut conflict attributes");
+      }
+      assert.equal(Reflect.get(attributes, "defaultCommand"), "terminal.toggle");
+      assert.equal(Reflect.get(attributes, "conflictingCommand"), "script.custom-action.run");
+      assert.equal(Reflect.get(attributes, "hasWhenContext"), false);
+      assert.isFalse("key" in attributes);
+      assert.isFalse("when" in attributes);
     }).pipe(
       Effect.provide(
         Layer.mergeAll(
@@ -443,15 +484,24 @@ it.layer(NodeServices.layer)("keybindings", (it) => {
           key: "mod+shift+r",
           command: "script.run-tests.run",
         });
-      }).pipe(toDetailResult);
-      assertFailure(result, "expected JSON array");
+      }).pipe(Effect.result);
+      if (Result.isSuccess(result)) {
+        return assert.fail("Expected malformed config update to fail");
+      }
+      assert.equal(result.failure._tag, "KeybindingsConfigError");
+      assert.equal(result.failure.operation, "decode");
+      assert.isTrue(Schema.isSchemaError(result.failure.cause));
+      assert.equal(
+        result.failure.message,
+        `Keybindings config operation 'decode' failed at ${keybindingsConfigPath}.`,
+      );
 
       const persistedRaw = yield* fs.readFileString(keybindingsConfigPath);
       assert.equal(persistedRaw, "{ not-json");
     }).pipe(Effect.provide(makeKeybindingsLayer())),
   );
 
-  it.effect("reports non-array config parse errors without duplicate prefix", () =>
+  it.effect("returns stable structured decode errors across retries", () =>
     Effect.gen(function* () {
       const fs = yield* FileSystem.FileSystem;
       const { keybindingsConfigPath } = yield* ServerConfig.ServerConfig;
@@ -466,8 +516,12 @@ it.layer(NodeServices.layer)("keybindings", (it) => {
           key: "mod+shift+r",
           command: "script.run-tests.run",
         });
-      }).pipe(toDetailResult);
-      assertFailure(firstResult, "expected JSON array");
+      }).pipe(Effect.result);
+      if (Result.isSuccess(firstResult)) {
+        return assert.fail("Expected first malformed config update to fail");
+      }
+      assert.equal(firstResult.failure.operation, "decode");
+      assert.isTrue(Schema.isSchemaError(firstResult.failure.cause));
 
       const secondResult = yield* Effect.gen(function* () {
         const keybindings = yield* Keybindings.Keybindings;
@@ -475,8 +529,13 @@ it.layer(NodeServices.layer)("keybindings", (it) => {
           key: "mod+shift+r",
           command: "script.run-tests.run",
         });
-      }).pipe(toDetailResult);
-      assertFailure(secondResult, "expected JSON array");
+      }).pipe(Effect.result);
+      if (Result.isSuccess(secondResult)) {
+        return assert.fail("Expected second malformed config update to fail");
+      }
+      assert.equal(secondResult.failure.operation, "decode");
+      assert.isTrue(Schema.isSchemaError(secondResult.failure.cause));
+      assert.equal(secondResult.failure.message, firstResult.failure.message);
     }).pipe(Effect.provide(makeKeybindingsLayer())),
   );
 
@@ -496,8 +555,11 @@ it.layer(NodeServices.layer)("keybindings", (it) => {
           key: "mod+shift+r",
           command: "script.run-tests.run",
         });
-      }).pipe(toDetailResult);
-      assertFailure(result, "failed to write keybindings config");
+      }).pipe(Effect.result);
+      if (Result.isSuccess(result)) {
+        return assert.fail("Expected update in a read-only directory to fail");
+      }
+      assert.equal(result.failure.operation, "write");
 
       yield* fs.chmod(dirname(keybindingsConfigPath), 0o700);
 
diff --git a/apps/server/src/keybindings.ts b/apps/server/src/keybindings.ts
index 5ddae4943f8..baca9a6d71d 100644
--- a/apps/server/src/keybindings.ts
+++ b/apps/server/src/keybindings.ts
@@ -44,6 +44,7 @@ import * as Semaphore from "effect/Semaphore";
 import * as ServerConfig from "./config.ts";
 import { writeFileStringAtomically } from "./atomicWrite.ts";
 import { fromJsonStringPretty, fromLenientJson } from "@t3tools/shared/schemaJson";
+import { causeErrorTag } from "@t3tools/shared/observability";
 import {
   DEFAULT_KEYBINDINGS,
   DEFAULT_RESOLVED_KEYBINDINGS,
@@ -186,23 +187,53 @@ export interface KeybindingsChangeEvent {
   readonly issues: readonly ServerConfigIssue[];
 }
 
-function trimIssueMessage(message: string): string {
-  const trimmed = message.trim();
-  return trimmed.length > 0 ? trimmed : "Invalid keybindings configuration.";
-}
+const MALFORMED_KEYBINDINGS_CONFIG_MESSAGE =
+  "Expected the keybindings configuration to be a JSON array.";
+const INVALID_KEYBINDING_ENTRY_MESSAGE =
+  "Expected a keybinding entry with key, command, and optional when fields.";
+const INVALID_KEYBINDING_RULE_MESSAGE =
+  "The keybinding entry contains an invalid shortcut or when expression.";
 
-function malformedConfigIssue(detail: string): ServerConfigIssue {
+function keybindingsCauseLogAttributes(cause: Cause.Cause<unknown>) {
   return {
-    kind: "keybindings.malformed-config",
-    message: trimIssueMessage(detail),
+    errorTag: causeErrorTag(cause),
+    causeReasonCount: cause.reasons.length,
+    causeFailureCount: cause.reasons.filter(Cause.isFailReason).length,
+    causeDefectCount: cause.reasons.filter(Cause.isDieReason).length,
+    causeInterruptionCount: cause.reasons.filter(Cause.isInterruptReason).length,
   };
 }
 
-function invalidEntryIssue(index: number, detail: string): ServerConfigIssue {
+function keybindingsValidationInputLogAttributes(value: unknown) {
+  if (typeof value === "string") {
+    return { validationInputKind: "string", validationInputSize: value.length };
+  }
+  if (Array.isArray(value)) {
+    return { validationInputKind: "array", validationInputSize: value.length };
+  }
+  if (typeof value === "object" && value !== null) {
+    return {
+      validationInputKind: "object",
+      validationInputSize: Object.keys(value).length,
+      validationHasKeyField: Object.hasOwn(value, "key"),
+      validationHasCommandField: Object.hasOwn(value, "command"),
+      validationHasWhenField: Object.hasOwn(value, "when"),
+    };
+  }
+  return { validationInputKind: value === null ? "null" : typeof value };
+}
+
+function keybindingsValidationLogAttributes(input: {
+  readonly stage: "document" | "entry-schema" | "resolved-rule";
+  readonly value: unknown;
+  readonly cause: Cause.Cause<unknown>;
+  readonly index?: number;
+}) {
   return {
-    kind: "keybindings.invalid-entry",
-    index,
-    message: trimIssueMessage(detail),
+    validationStage: input.stage,
+    ...(input.index === undefined ? {} : { entryIndex: input.index }),
+    ...keybindingsValidationInputLogAttributes(input.value),
+    ...keybindingsCauseLogAttributes(input.cause),
   };
 }
 
@@ -306,7 +337,7 @@ const make = Effect.gen(function* () {
       (cause) =>
         new KeybindingsConfigError({
           configPath: keybindingsConfigPath,
-          detail: "failed to access keybindings config",
+          operation: "access",
           cause,
         }),
     ),
@@ -317,7 +348,7 @@ const make = Effect.gen(function* () {
       (cause) =>
         new KeybindingsConfigError({
           configPath: keybindingsConfigPath,
-          detail: "failed to read keybindings config",
+          operation: "read",
           cause,
         }),
     ),
@@ -337,20 +368,24 @@ const make = Effect.gen(function* () {
         (cause) =>
           new KeybindingsConfigError({
             configPath: keybindingsConfigPath,
-            detail: "expected JSON array",
+            operation: "decode",
             cause,
           }),
       ),
     );
 
-    return yield* Effect.forEach(rawConfig, (entry) =>
+    return yield* Effect.forEach(rawConfig, (entry, index) =>
       Effect.gen(function* () {
         const decodedRule = decodeKeybindingRuleExit(entry);
         if (decodedRule._tag === "Failure") {
           yield* Effect.logWarning("ignoring invalid keybinding entry", {
             path: keybindingsConfigPath,
-            entry,
-            error: Cause.pretty(decodedRule.cause),
+            ...keybindingsValidationLogAttributes({
+              stage: "entry-schema",
+              value: entry,
+              cause: decodedRule.cause,
+              index,
+            }),
           });
           return null;
         }
@@ -358,8 +393,12 @@ const make = Effect.gen(function* () {
         if (resolved._tag === "Failure") {
           yield* Effect.logWarning("ignoring invalid keybinding entry", {
             path: keybindingsConfigPath,
-            entry,
-            error: Cause.pretty(resolved.cause),
+            ...keybindingsValidationLogAttributes({
+              stage: "resolved-rule",
+              value: entry,
+              cause: resolved.cause,
+              index,
+            }),
           });
           return null;
         }
@@ -382,10 +421,22 @@ const make = Effect.gen(function* () {
     const rawConfig = yield* readRawConfig;
     const decodedEntries = decodeRawKeybindingsEntriesExit(rawConfig);
     if (decodedEntries._tag === "Failure") {
-      const detail = `expected JSON array (${Cause.pretty(decodedEntries.cause)})`;
+      yield* Effect.logWarning("ignoring malformed keybindings config", {
+        path: keybindingsConfigPath,
+        ...keybindingsValidationLogAttributes({
+          stage: "document",
+          value: rawConfig,
+          cause: decodedEntries.cause,
+        }),
+      });
       return {
         keybindings: [],
-        issues: [malformedConfigIssue(detail)],
+        issues: [
+          {
+            kind: "keybindings.malformed-config",
+            message: MALFORMED_KEYBINDINGS_CONFIG_MESSAGE,
+          },
+        ],
       };
     }
 
@@ -394,26 +445,38 @@ const make = Effect.gen(function* () {
     for (const [index, entry] of decodedEntries.value.entries()) {
       const decodedRule = decodeKeybindingRuleExit(entry);
       if (decodedRule._tag === "Failure") {
-        const detail = Cause.pretty(decodedRule.cause);
-        issues.push(invalidEntryIssue(index, detail));
+        issues.push({
+          kind: "keybindings.invalid-entry",
+          index,
+          message: INVALID_KEYBINDING_ENTRY_MESSAGE,
+        });
         yield* Effect.logWarning("ignoring invalid keybinding entry", {
           path: keybindingsConfigPath,
-          index,
-          entry,
-          error: detail,
+          ...keybindingsValidationLogAttributes({
+            stage: "entry-schema",
+            value: entry,
+            cause: decodedRule.cause,
+            index,
+          }),
         });
         continue;
       }
 
       const resolvedRule = decodeResolvedKeybindingFromConfigExit(decodedRule.value);
       if (resolvedRule._tag === "Failure") {
-        const detail = Cause.pretty(resolvedRule.cause);
-        issues.push(invalidEntryIssue(index, detail));
+        issues.push({
+          kind: "keybindings.invalid-entry",
+          index,
+          message: INVALID_KEYBINDING_RULE_MESSAGE,
+        });
         yield* Effect.logWarning("ignoring invalid keybinding entry", {
           path: keybindingsConfigPath,
-          index,
-          entry,
-          error: detail,
+          ...keybindingsValidationLogAttributes({
+            stage: "resolved-rule",
+            value: entry,
+            cause: resolvedRule.cause,
+            index,
+          }),
         });
         continue;
       }
@@ -425,6 +488,14 @@ const make = Effect.gen(function* () {
 
   const writeConfigAtomically = (rules: readonly KeybindingRule[]) => {
     return encodeKeybindingsConfigPrettyJson(rules).pipe(
+      Effect.mapError(
+        (cause) =>
+          new KeybindingsConfigError({
+            configPath: keybindingsConfigPath,
+            operation: "encode",
+            cause,
+          }),
+      ),
       Effect.map((encoded) => `${encoded}\n`),
       Effect.flatMap((encoded) =>
         writeFileStringAtomically({
@@ -433,16 +504,16 @@ const make = Effect.gen(function* () {
         }).pipe(
           Effect.provideService(FileSystem.FileSystem, fs),
           Effect.provideService(Path.Path, path),
+          Effect.mapError(
+            (cause) =>
+              new KeybindingsConfigError({
+                configPath: keybindingsConfigPath,
+                operation: "write",
+                cause,
+              }),
+          ),
         ),
       ),
-      Effect.mapError(
-        (cause) =>
-          new KeybindingsConfigError({
-            configPath: keybindingsConfigPath,
-            detail: "failed to write keybindings config",
-            cause,
-          }),
-      ),
     );
   };
 
@@ -487,7 +558,13 @@ const make = Effect.gen(function* () {
           "skipping startup keybindings default sync because config has issues",
           {
             path: keybindingsConfigPath,
-            issues: runtimeConfig.issues,
+            issueCount: runtimeConfig.issues.length,
+            malformedConfigIssueCount: runtimeConfig.issues.filter(
+              (issue) => issue.kind === "keybindings.malformed-config",
+            ).length,
+            invalidEntryIssueCount: runtimeConfig.issues.filter(
+              (issue) => issue.kind === "keybindings.invalid-entry",
+            ).length,
           },
         );
         yield* Cache.invalidate(resolvedConfigCache, resolvedConfigCacheKey);
@@ -499,8 +576,7 @@ const make = Effect.gen(function* () {
       const shortcutConflictWarnings: Array<{
         defaultCommand: KeybindingRule["command"];
         conflictingCommand: KeybindingRule["command"];
-        key: string;
-        when: string | null;
+        hasWhenContext: boolean;
       }> = [];
       for (const defaultRule of DEFAULT_KEYBINDINGS) {
         if (existingCommands.has(defaultRule.command)) {
@@ -513,8 +589,7 @@ const make = Effect.gen(function* () {
           shortcutConflictWarnings.push({
             defaultCommand: defaultRule.command,
             conflictingCommand: conflictingEntry.command,
-            key: defaultRule.key,
-            when: defaultRule.when ?? null,
+            hasWhenContext: defaultRule.when !== undefined,
           });
           continue;
         }
@@ -525,8 +600,7 @@ const make = Effect.gen(function* () {
           path: keybindingsConfigPath,
           defaultCommand: conflict.defaultCommand,
           conflictingCommand: conflict.conflictingCommand,
-          key: conflict.key,
-          when: conflict.when,
+          hasWhenContext: conflict.hasWhenContext,
           reason: "shortcut context already used by existing rule",
         });
       }
@@ -574,13 +648,22 @@ const make = Effect.gen(function* () {
         (cause) =>
           new KeybindingsConfigError({
             configPath: keybindingsConfigPath,
-            detail: "failed to prepare keybindings config directory",
+            operation: "prepare-directory",
             cause,
           }),
       ),
     );
 
-    const revalidateAndEmitSafely = revalidateAndEmit.pipe(Effect.ignoreCause({ log: true }));
+    const revalidateAndEmitSafely = revalidateAndEmit.pipe(
+      Effect.catchCause((cause) =>
+        Cause.hasInterruptsOnly(cause)
+          ? Effect.void
+          : Effect.logWarning("keybindings config revalidation failed", {
+              path: keybindingsConfigPath,
+              ...keybindingsCauseLogAttributes(cause),
+            }),
+      ),
+    );
 
     // Debounce watch events so the file is fully written before we read it.
     // Editors emit multiple events per save (truncate, write, rename) and
@@ -597,7 +680,14 @@ const make = Effect.gen(function* () {
     );
 
     yield* Stream.runForEach(debouncedKeybindingsEvents, () => revalidateAndEmitSafely).pipe(
-      Effect.ignoreCause({ log: true }),
+      Effect.catchCause((cause) =>
+        Cause.hasInterruptsOnly(cause)
+          ? Effect.void
+          : Effect.logWarning("keybindings config watcher failed", {
+              path: keybindingsConfigPath,
+              ...keybindingsCauseLogAttributes(cause),
+            }),
+      ),
       Effect.forkIn(watcherScope),
       Effect.asVoid,
     );
diff --git a/apps/server/src/relay/AgentAwarenessRelay.test.ts b/apps/server/src/relay/AgentAwarenessRelay.test.ts
index 40ed694723d..79aa1bebe99 100644
--- a/apps/server/src/relay/AgentAwarenessRelay.test.ts
+++ b/apps/server/src/relay/AgentAwarenessRelay.test.ts
@@ -20,6 +20,7 @@ import { CommandId, ProviderInstanceId } from "@t3tools/contracts";
 import { RelayClientTracer } from "@t3tools/shared/relayTracing";
 import { RELAY_ACTIVITY_PUBLISH_TYP, verifyRelayJwt } from "@t3tools/shared/relayJwt";
 import { describe, expect, it } from "@effect/vitest";
+import * as Cause from "effect/Cause";
 import * as Deferred from "effect/Deferred";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
@@ -98,6 +99,50 @@ function makeMemorySecretStore() {
 }
 
 describe.sequential("signRelayAgentActivityPublishProof", () => {
+  it("redacts relay URL secrets from log attributes", () => {
+    const relayUrl =
+      "https://relay-user:relay-password@relay.example.test/private/path?token=relay-secret#fragment";
+    const attributes = AgentAwarenessRelay.relayUrlLogAttributes(relayUrl);
+
+    expect(attributes).toEqual({
+      relayUrlConfigured: true,
+      relayUrlInputLength: relayUrl.length,
+      relayUrlProtocol: "https:",
+      relayUrlHostname: "relay.example.test",
+    });
+    const renderedAttributes = Object.values(attributes).join(" ");
+    expect(renderedAttributes).not.toContain("relay-user");
+    expect(renderedAttributes).not.toContain("relay-password");
+    expect(renderedAttributes).not.toContain("private/path");
+    expect(renderedAttributes).not.toContain("relay-secret");
+    expect(renderedAttributes).not.toContain("fragment");
+  });
+
+  it("summarizes publish causes without serializing nested failures or defects", () => {
+    const privateFailureDetail = "private relay response body";
+    const privateDefectDetail = "private relay defect detail";
+    const cause = Cause.combine(
+      Cause.fail({
+        _tag: "RelayPublishError",
+        cause: new Error(privateFailureDetail),
+        detail: privateFailureDetail,
+      }),
+      Cause.die(new Error(privateDefectDetail)),
+    );
+    const attributes = AgentAwarenessRelay.relayPublishCauseLogAttributes(cause);
+
+    expect(attributes).toEqual({
+      causeReasonCount: 2,
+      causeFailureCount: 1,
+      causeDefectCount: 1,
+      causeInterruptionCount: 0,
+      causeFailureTags: ["RelayPublishError"],
+    });
+    const renderedAttributes = Object.values(attributes).join(" ");
+    expect(renderedAttributes).not.toContain(privateFailureDetail);
+    expect(renderedAttributes).not.toContain(privateDefectDetail);
+  });
+
   it("distinguishes pending link credentials from disabled publication", () => {
     expect(
       AgentAwarenessRelay.resolveAgentActivityPublishingStartupState({
diff --git a/apps/server/src/relay/AgentAwarenessRelay.ts b/apps/server/src/relay/AgentAwarenessRelay.ts
index 4e036e3ea0e..0b955bcd5c6 100644
--- a/apps/server/src/relay/AgentAwarenessRelay.ts
+++ b/apps/server/src/relay/AgentAwarenessRelay.ts
@@ -18,6 +18,7 @@ import {
   RELAY_ACTIVITY_PUBLISH_TYP,
   signRelayJwt,
 } from "@t3tools/shared/relayJwt";
+import { getUrlDiagnostics } from "@t3tools/shared/urlDiagnostics";
 import * as Cause from "effect/Cause";
 import * as Context from "effect/Context";
 import * as Crypto from "effect/Crypto";
@@ -98,6 +99,44 @@ export function isAgentActivityPublishingEnabled(value: string | null): boolean
   return value === "true";
 }
 
+export function relayUrlLogAttributes(relayUrl: string | undefined) {
+  if (relayUrl === undefined) {
+    return { relayUrlConfigured: false };
+  }
+  const diagnostics = getUrlDiagnostics(relayUrl);
+  return {
+    relayUrlConfigured: true,
+    relayUrlInputLength: diagnostics.inputLength,
+    ...(diagnostics.protocol === undefined ? {} : { relayUrlProtocol: diagnostics.protocol }),
+    ...(diagnostics.hostname === undefined ? {} : { relayUrlHostname: diagnostics.hostname }),
+  };
+}
+
+export function relayPublishCauseLogAttributes(cause: Cause.Cause<unknown>) {
+  const failureTags = cause.reasons.flatMap((reason) => {
+    if (!Cause.isFailReason(reason)) {
+      return [];
+    }
+    const error = reason.error;
+    if (
+      typeof error !== "object" ||
+      error === null ||
+      !("_tag" in error) ||
+      typeof error._tag !== "string"
+    ) {
+      return [];
+    }
+    return [error._tag];
+  });
+  return {
+    causeReasonCount: cause.reasons.length,
+    causeFailureCount: cause.reasons.filter(Cause.isFailReason).length,
+    causeDefectCount: cause.reasons.filter(Cause.isDieReason).length,
+    causeInterruptionCount: cause.reasons.filter(Cause.isInterruptReason).length,
+    causeFailureTags: [...new Set(failureTags)],
+  };
+}
+
 export function resolveAgentActivityPublishingStartupState(input: {
   readonly relayConfigured: boolean;
   readonly publishEnabled: boolean;
@@ -417,12 +456,12 @@ export const make = Effect.gen(function* () {
 
   const publishThread: AgentAwarenessRelay["Service"]["publishThread"] = (threadId) =>
     publishThreadUnsafe(threadId).pipe(
-      Effect.catchCause((cause) => {
-        return Effect.logWarning("agent activity publish failed", {
+      Effect.catchCause((cause) =>
+        Effect.logWarning("agent activity publish failed", {
           threadId,
-          cause: Cause.pretty(cause),
-        });
-      }),
+          ...relayPublishCauseLogAttributes(cause),
+        }),
+      ),
       Effect.withSpan("AgentAwarenessRelay.publishThread"),
       withRelayClientTracing,
     );
@@ -467,7 +506,7 @@ export const make = Effect.gen(function* () {
           if (logEnabledWhenReady) {
             const relayConfig = yield* readRelayConfig.pipe(Effect.orElseSucceed(() => null));
             yield* Effect.logInfo("agent activity publishing enabled after link reconciliation", {
-              relayUrl: relayConfig?.url,
+              ...relayUrlLogAttributes(relayConfig?.url),
             });
           }
           return;
@@ -499,7 +538,7 @@ export const make = Effect.gen(function* () {
           break;
         case "enabled":
           yield* Effect.logInfo("agent activity publishing enabled", {
-            relayUrl: relayConfig?.url,
+            ...relayUrlLogAttributes(relayConfig?.url),
           });
           break;
       }
diff --git a/apps/server/src/server.test.ts b/apps/server/src/server.test.ts
index e1daf20ed57..9feef4e5200 100644
--- a/apps/server/src/server.test.ts
+++ b/apps/server/src/server.test.ts
@@ -4027,6 +4027,31 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
       }).pipe(Effect.provide(NodeHttpServer.layerTest)),
   );
 
+  it.effect("continues browser OTLP requests when local trace collection defects", () =>
+    Effect.gen(function* () {
+      const payload = yield* makeBrowserOtlpPayload("client.test");
+
+      yield* buildAppUnderTest({
+        layers: {
+          browserTraceCollector: {
+            record: () => Effect.die(new Error("private local collector failure")),
+          },
+        },
+      });
+
+      const response = yield* HttpClient.post("/api/observability/v1/traces", {
+        headers: {
+          cookie: yield* getAuthenticatedSessionCookieHeader(),
+          "content-type": "application/json",
+        },
+        // @effect-diagnostics-next-line preferSchemaOverJson:off
+        body: HttpBody.text(JSON.stringify(payload), "application/json"),
+      });
+
+      assert.equal(response.status, 204);
+    }).pipe(Effect.provide(NodeHttpServer.layerTest)),
+  );
+
   it.effect("routes websocket rpc server.upsertKeybinding", () =>
     Effect.gen(function* () {
       const rule: KeybindingRule = {
diff --git a/apps/server/src/serverRuntimeStartup.ts b/apps/server/src/serverRuntimeStartup.ts
index b52b577c5b5..b401a1e5df2 100644
--- a/apps/server/src/serverRuntimeStartup.ts
+++ b/apps/server/src/serverRuntimeStartup.ts
@@ -309,13 +309,14 @@ export const make = Effect.gen(function* () {
     yield* runStartupPhase(
       "keybindings.start",
       keybindings.start.pipe(
-        Effect.catch((error) =>
-          Effect.logWarning("failed to start keybindings runtime", {
-            path: error.configPath,
-            detail: error.detail,
-            cause: error.cause,
-          }),
-        ),
+        Effect.catchTags({
+          KeybindingsConfigError: (error) =>
+            Effect.logWarning("failed to start keybindings runtime", {
+              path: error.configPath,
+              operation: error.operation,
+              errorTag: error._tag,
+            }),
+        }),
         Effect.forkScoped,
       ),
     );
diff --git a/apps/server/src/serverSettings.test.ts b/apps/server/src/serverSettings.test.ts
index 504d99e18de..d9df8fec1b0 100644
--- a/apps/server/src/serverSettings.test.ts
+++ b/apps/server/src/serverSettings.test.ts
@@ -33,7 +33,7 @@ const makeServerSettingsLayer = () =>
     ),
   );
 
-const makeFailingSecretStoreLayer = (cause: ServerSecretStore.SecretStoreError) =>
+const makeFailingSecretStoreLayer = (cause: ServerSecretStore.SecretStoreReadError) =>
   Layer.succeed(
     ServerSecretStore.ServerSecretStore,
     ServerSecretStore.ServerSecretStore.of({
@@ -55,7 +55,8 @@ it.layer(NodeServices.layer)("server settings", (it) => {
       description: "Secret backend unavailable.",
     });
     const cause = new ServerSecretStore.SecretStoreReadError({
-      resource: "provider environment secret",
+      secretName: "provider environment secret",
+      secretPath: "/test/secrets/provider-environment-secret.bin",
       cause: platformCause,
     });
     const configLayer = Layer.fresh(
diff --git a/apps/server/src/telemetry/AnalyticsService.test.ts b/apps/server/src/telemetry/AnalyticsService.test.ts
index d69bab32feb..dd221ff176f 100644
--- a/apps/server/src/telemetry/AnalyticsService.test.ts
+++ b/apps/server/src/telemetry/AnalyticsService.test.ts
@@ -4,7 +4,11 @@ import { assert, it } from "@effect/vitest";
 import * as ConfigProvider from "effect/ConfigProvider";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
+import * as Logger from "effect/Logger";
+import * as References from "effect/References";
+import * as Schema from "effect/Schema";
 import * as HttpServer from "effect/unstable/http/HttpServer";
+import * as HttpClientError from "effect/unstable/http/HttpClientError";
 import * as HttpServerRequest from "effect/unstable/http/HttpServerRequest";
 import * as HttpServerResponse from "effect/unstable/http/HttpServerResponse";
 
@@ -35,10 +39,25 @@ interface RecordedBatchBody {
   }>;
 }
 
+interface CapturedLog {
+  readonly message: unknown;
+  readonly annotations: Readonly<Record<string, unknown>>;
+}
+
+const isAnalyticsBatchDeliveryError = Schema.is(AnalyticsService.AnalyticsBatchDeliveryError);
+
 it.layer(NodeServices.layer)("AnalyticsService test", (it) => {
-  it.effect("flush drains all buffered events across multiple batches", () =>
+  it.effect("flush drains buffered events and retries failed batches with structured context", () =>
     Effect.gen(function* () {
       const capturedRequests: Array<RecordedBatchRequest> = [];
+      const capturedLogs: CapturedLog[] = [];
+      let rejectNextBatch = false;
+      const logger = Logger.make(({ fiber, message }) => {
+        capturedLogs.push({
+          message,
+          annotations: fiber.getRef(References.CurrentLogAnnotations),
+        });
+      });
       const serverConfigLayer = ServerConfig.ServerConfig.layerTest(process.cwd(), {
         prefix: "t3-telemetry-base-",
       });
@@ -66,12 +85,20 @@ it.layer(NodeServices.layer)("AnalyticsService test", (it) => {
 
           capturedRequests.push({ path: request.url, body: payload });
 
+          if (rejectNextBatch) {
+            rejectNextBatch = false;
+            return HttpServerResponse.empty({ status: 503 });
+          }
+
           return HttpServerResponse.jsonUnsafe({});
         }),
       );
-      const runtimeLayer = telemetryLayer.pipe(
-        Layer.provide(configLayer),
-        Layer.provideMerge(NodeHttpServer.layerTest),
+      const runtimeLayer = Layer.merge(
+        telemetryLayer.pipe(
+          Layer.provide(configLayer),
+          Layer.provideMerge(NodeHttpServer.layerTest),
+        ),
+        Logger.layer([logger], { mergeWithExisting: false }),
       );
 
       yield* Effect.gen(function* () {
@@ -85,12 +112,17 @@ it.layer(NodeServices.layer)("AnalyticsService test", (it) => {
         }
 
         yield* analytics.flush;
+        yield* analytics.record("test.flush.retry", { index: 45 });
+        rejectNextBatch = true;
+        yield* analytics.flush;
+        yield* analytics.flush;
       }).pipe(Effect.provide(runtimeLayer));
 
-      const batchRequests = capturedRequests.filter(
-        (request): request is RecordedBatchRequest & { readonly body: RecordedBatchBody } =>
+      const batchRequests = capturedRequests
+        .slice(0, 3)
+        .filter((request): request is RecordedBatchRequest & { readonly body: RecordedBatchBody } =>
           Array.isArray(request.body?.batch),
-      );
+        );
       assert.equal(batchRequests.length, 3);
       assert.equal(
         batchRequests.every((request) => request.path === "/batch/" || request.path === "/batch"),
@@ -115,6 +147,53 @@ it.layer(NodeServices.layer)("AnalyticsService test", (it) => {
         ),
         true,
       );
+
+      const retryRequests = capturedRequests.slice(3);
+      assert.equal(retryRequests.length, 2);
+      assert.deepEqual(retryRequests[0]?.body, retryRequests[1]?.body);
+
+      const deliveryLog = capturedLogs.find((log) =>
+        isAnalyticsBatchDeliveryError(log.annotations.cause),
+      );
+      assert.isDefined(deliveryLog);
+      assert.equal(
+        deliveryLog?.message,
+        "Failed to deliver 1 analytics event to PostHog (endpoint input length 7).",
+      );
+      assert.equal("endpoint" in deliveryLog.annotations, false);
+      assert.equal(deliveryLog.annotations.endpointInputLength, 7);
+
+      const error = deliveryLog?.annotations.cause;
+      assert.instanceOf(error, AnalyticsService.AnalyticsBatchDeliveryError);
+      if (isAnalyticsBatchDeliveryError(error)) {
+        assert.equal(error.endpointInputLength, 7);
+        assert.equal(error.endpointProtocol, undefined);
+        assert.equal(error.endpointHostname, undefined);
+        assert.equal(error.eventCount, 1);
+        assert.instanceOf(error.cause, HttpClientError.HttpClientError);
+        if (error.cause instanceof HttpClientError.HttpClientError) {
+          assert.equal(error.cause.reason._tag, "StatusCodeError");
+          assert.equal(error.cause.response?.status, 503);
+        }
+      }
     }),
   );
 });
+
+it("keeps configured PostHog endpoint secrets out of direct error and log context", () => {
+  const endpoint =
+    "https://user:password@posthog.example.test/private/project?api_key=secret#fragment";
+  const cause = new Error("delivery failed");
+  const error = AnalyticsService.AnalyticsBatchDeliveryError.fromEndpoint({
+    endpoint,
+    eventCount: 2,
+    cause,
+  });
+
+  assert.equal(error.endpointInputLength, endpoint.length);
+  assert.equal(error.endpointProtocol, "https:");
+  assert.equal(error.endpointHostname, "posthog.example.test");
+  assert.equal(error.cause, cause);
+  assert.equal("endpoint" in error, false);
+  assert.equal(/user|password|private|project|api_key|secret|fragment/.test(error.message), false);
+});
diff --git a/apps/server/src/telemetry/AnalyticsService.ts b/apps/server/src/telemetry/AnalyticsService.ts
index 5fdc7bdeb19..30454b5d5ab 100644
--- a/apps/server/src/telemetry/AnalyticsService.ts
+++ b/apps/server/src/telemetry/AnalyticsService.ts
@@ -7,6 +7,7 @@
  * @module AnalyticsService
  */
 import { HostProcessArchitecture, HostProcessPlatform } from "@t3tools/shared/hostProcess";
+import { getUrlDiagnostics } from "@t3tools/shared/urlDiagnostics";
 import * as Config from "effect/Config";
 import * as Context from "effect/Context";
 import * as DateTime from "effect/DateTime";
@@ -14,6 +15,7 @@ import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as Option from "effect/Option";
 import * as Ref from "effect/Ref";
+import * as Schema from "effect/Schema";
 import * as HttpClient from "effect/unstable/http/HttpClient";
 import * as HttpClientRequest from "effect/unstable/http/HttpClientRequest";
 import * as HttpClientResponse from "effect/unstable/http/HttpClientResponse";
@@ -43,6 +45,38 @@ const TelemetryEnvConfig = Config.all({
   wslDistroName: Config.string("WSL_DISTRO_NAME").pipe(Config.option),
 });
 
+export class AnalyticsBatchDeliveryError extends Schema.TaggedErrorClass<AnalyticsBatchDeliveryError>()(
+  "AnalyticsBatchDeliveryError",
+  {
+    endpointInputLength: Schema.Number,
+    endpointProtocol: Schema.optionalKey(Schema.String),
+    endpointHostname: Schema.optionalKey(Schema.String),
+    eventCount: Schema.Int.check(Schema.isGreaterThan(0)),
+    cause: Schema.Defect(),
+  },
+) {
+  static fromEndpoint(input: {
+    readonly endpoint: string;
+    readonly eventCount: number;
+    readonly cause: unknown;
+  }): AnalyticsBatchDeliveryError {
+    const diagnostics = getUrlDiagnostics(input.endpoint);
+    return new AnalyticsBatchDeliveryError({
+      endpointInputLength: diagnostics.inputLength,
+      ...(diagnostics.protocol === undefined ? {} : { endpointProtocol: diagnostics.protocol }),
+      ...(diagnostics.hostname === undefined ? {} : { endpointHostname: diagnostics.hostname }),
+      eventCount: input.eventCount,
+      cause: input.cause,
+    });
+  }
+
+  override get message(): string {
+    const eventLabel = this.eventCount === 1 ? "event" : "events";
+    const destination = this.endpointHostname ? ` at ${this.endpointHostname}` : "";
+    return `Failed to deliver ${this.eventCount} analytics ${eventLabel} to PostHog${destination} (endpoint input length ${this.endpointInputLength}).`;
+  }
+}
+
 export class AnalyticsService extends Context.Service<
   AnalyticsService,
   {
@@ -75,6 +109,7 @@ export const make = Effect.gen(function* () {
   const clientType = serverConfig.mode === "desktop" ? "desktop-app" : "cli-web-client";
   const hostPlatform = yield* HostProcessPlatform;
   const hostArchitecture = yield* HostProcessArchitecture;
+  const batchEndpoint = `${telemetryConfig.posthogHost}/batch/`;
 
   const enqueueBufferedEvent = (event: string, properties?: Readonly<Record<string, unknown>>) =>
     Effect.flatMap(DateTime.now, (now) =>
@@ -126,10 +161,17 @@ export const make = Effect.gen(function* () {
       })),
     };
 
-    yield* HttpClientRequest.post(`${telemetryConfig.posthogHost}/batch/`).pipe(
+    yield* HttpClientRequest.post(batchEndpoint).pipe(
       HttpClientRequest.bodyJson(payload),
       Effect.flatMap(httpClient.execute),
       Effect.flatMap(HttpClientResponse.filterStatusOk),
+      Effect.mapError((cause) =>
+        AnalyticsBatchDeliveryError.fromEndpoint({
+          endpoint: batchEndpoint,
+          eventCount: events.length,
+          cause,
+        }),
+      ),
     );
   });
 
@@ -149,14 +191,32 @@ export const make = Effect.gen(function* () {
       }
 
       yield* sendBatch(batch).pipe(
-        Effect.catch((error) =>
-          Ref.update(bufferRef, (current) => [...batch, ...current]).pipe(
-            Effect.flatMap(() => Effect.fail(error)),
-          ),
-        ),
+        Effect.catchTags({
+          AnalyticsBatchDeliveryError: (error) =>
+            Ref.update(bufferRef, (current) => [...batch, ...current]).pipe(
+              Effect.flatMap(() => Effect.fail(error)),
+            ),
+        }),
       );
     }
-  }).pipe(Effect.catch((cause) => Effect.logError("Failed to flush telemetry", { cause })));
+  }).pipe(
+    Effect.catchTags({
+      AnalyticsBatchDeliveryError: (error) =>
+        Effect.logError(error.message).pipe(
+          Effect.annotateLogs({
+            endpointInputLength: error.endpointInputLength,
+            ...(error.endpointProtocol === undefined
+              ? {}
+              : { endpointProtocol: error.endpointProtocol }),
+            ...(error.endpointHostname === undefined
+              ? {}
+              : { endpointHostname: error.endpointHostname }),
+            eventCount: error.eventCount,
+            cause: error,
+          }),
+        ),
+    }),
+  );
 
   const record: AnalyticsService["Service"]["record"] = Effect.fn("AnalyticsService.record")(
     function* (event, properties) {
diff --git a/apps/server/src/ws.ts b/apps/server/src/ws.ts
index 554a942d78a..b4f7f78e28d 100644
--- a/apps/server/src/ws.ts
+++ b/apps/server/src/ws.ts
@@ -110,7 +110,7 @@ import * as VcsProjectConfig from "./vcs/VcsProjectConfig.ts";
 import * as VcsProcess from "./vcs/VcsProcess.ts";
 import * as PairingGrantStore from "./auth/PairingGrantStore.ts";
 import * as SessionStore from "./auth/SessionStore.ts";
-import { failEnvironmentAuthInvalid, failEnvironmentInternal } from "./auth/http.ts";
+import { catchEnvironmentAuthenticationErrors } from "./auth/http.ts";
 import * as RelayClient from "@t3tools/shared/relayClient";
 const isOrchestrationDispatchCommandError = Schema.is(OrchestrationDispatchCommandError);
 
@@ -510,16 +510,26 @@ const makeWsRpcLayer = (currentSession: EnvironmentAuth.AuthenticatedSession) =>
 
       const loadAuthAccessSnapshot = () =>
         Effect.all({
-          pairingLinks: serverAuth.listPairingLinks(),
-          clientSessions: serverAuth.listClientSessions(currentSessionId),
-        }).pipe(
-          Effect.mapError(
-            (error) =>
-              new AuthAccessStreamError({
-                message: error.message,
-              }),
+          pairingLinks: serverAuth.listPairingLinks().pipe(
+            Effect.mapError(
+              (cause) =>
+                new AuthAccessStreamError({
+                  operation: "list-pairing-links",
+                  cause,
+                }),
+            ),
           ),
-        );
+          clientSessions: serverAuth.listClientSessions(currentSessionId).pipe(
+            Effect.mapError(
+              (cause) =>
+                new AuthAccessStreamError({
+                  operation: "list-client-sessions",
+                  currentSessionId,
+                  cause,
+                }),
+            ),
+          ),
+        });
 
       const appendSetupScriptActivity = (input: {
         readonly threadId: ThreadId;
@@ -1279,15 +1289,16 @@ const makeWsRpcLayer = (currentSession: EnvironmentAuth.AuthenticatedSession) =>
                         status,
                       }),
                     ),
-                    Effect.catchTag("RelayClientInstallError", (error) =>
-                      Queue.fail(
-                        queue,
-                        new RelayClientInstallFailedError({
-                          reason: error.reason,
-                          message: error.message,
-                        }),
-                      ),
-                    ),
+                    Effect.catchTags({
+                      RelayClientInstallError: (error) =>
+                        Queue.fail(
+                          queue,
+                          new RelayClientInstallFailedError({
+                            reason: error.reason,
+                            message: error.message,
+                          }),
+                        ),
+                    }),
                     Effect.andThen(Queue.end(queue)),
                     Effect.forkScoped,
                   ),
@@ -1799,13 +1810,8 @@ export const websocketRpcRouteLayer = Layer.unwrap(
         const request = yield* HttpServerRequest.HttpServerRequest;
         const serverAuth = yield* EnvironmentAuth.EnvironmentAuth;
         const sessions = yield* SessionStore.SessionStore;
-        const session = yield* serverAuth.authenticateWebSocketUpgrade(request).pipe(
-          Effect.catchIf(EnvironmentAuth.isServerAuthCredentialError, (error) =>
-            failEnvironmentAuthInvalid(EnvironmentAuth.serverAuthCredentialReason(error)),
-          ),
-          Effect.catchIf(EnvironmentAuth.isServerAuthInternalError, (error) =>
-            failEnvironmentInternal("internal_error", error),
-          ),
+        const session = yield* catchEnvironmentAuthenticationErrors(
+          serverAuth.authenticateWebSocketUpgrade(request),
         );
         const rpcWebSocketHttpEffect = yield* RpcServer.toHttpEffectWebsocket(WsRpcGroup, {
           disableTracing: true,
diff --git a/apps/web/src/browser/browserTargetResolver.test.ts b/apps/web/src/browser/browserTargetResolver.test.ts
index 2305812784f..3a26985c23b 100644
--- a/apps/web/src/browser/browserTargetResolver.test.ts
+++ b/apps/web/src/browser/browserTargetResolver.test.ts
@@ -28,12 +28,71 @@ describe("browser target resolver", () => {
   it("refuses public relay hosts until the authenticated gateway exists", async () => {
     readPreparedConnection.mockReturnValue({ httpBaseUrl: "https://relay.example.com" });
     const { resolveBrowserNavigationTarget } = await import("./browserTargetResolver");
-    expect(() =>
+
+    try {
       resolveBrowserNavigationTarget(EnvironmentId.make("environment-1"), {
         kind: "environment-port",
         port: 5173,
-      }),
-    ).toThrow(/authenticated preview gateway/);
+      });
+      expect.unreachable("Expected public environment host resolution to fail");
+    } catch (error) {
+      expect(error).toMatchObject({
+        _tag: "BrowserTargetPrivateNetworkRequiredError",
+        environmentId: "environment-1",
+        hostname: "relay.example.com",
+        message:
+          "Environment environment-1 host relay.example.com needs the planned authenticated preview gateway because it is not directly private-network reachable.",
+      });
+    }
+  });
+
+  it("identifies the disconnected environment", async () => {
+    const { resolveBrowserNavigationTarget } = await import("./browserTargetResolver");
+
+    try {
+      resolveBrowserNavigationTarget(EnvironmentId.make("environment-1"), {
+        kind: "environment-port",
+        port: 5173,
+      });
+      expect.unreachable("Expected disconnected environment resolution to fail");
+    } catch (error) {
+      expect(error).toMatchObject({
+        _tag: "BrowserTargetEnvironmentDisconnectedError",
+        environmentId: "environment-1",
+        message: "Environment environment-1 is not connected.",
+      });
+    }
+  });
+
+  it("preserves invalid environment URL causes with connection context", async () => {
+    const sensitiveUrl =
+      "https://user:password@[invalid-host]/private/workspace?access_token=secret#fragment";
+    readPreparedConnection.mockReturnValue({ httpBaseUrl: sensitiveUrl });
+    const { BrowserTargetEnvironmentUrlInvalidError, resolveBrowserNavigationTarget } =
+      await import("./browserTargetResolver");
+
+    try {
+      resolveBrowserNavigationTarget(EnvironmentId.make("environment-1"), {
+        kind: "environment-port",
+        port: 5173,
+      });
+      expect.unreachable("Expected browser target resolution to fail");
+    } catch (error) {
+      expect(error).toMatchObject({
+        _tag: "BrowserTargetEnvironmentUrlInvalidError",
+        environmentId: "environment-1",
+        httpBaseUrlInputLength: sensitiveUrl.length,
+        cause: expect.any(TypeError),
+        message: `Environment environment-1 has an invalid HTTP base URL input of length ${sensitiveUrl.length}.`,
+      });
+      expect(error).toBeInstanceOf(BrowserTargetEnvironmentUrlInvalidError);
+      expect(error).not.toHaveProperty("httpBaseUrl");
+      expect(error).not.toHaveProperty("httpBaseUrlProtocol");
+      expect(error).not.toHaveProperty("httpBaseUrlHostname");
+      expect(String((error as Error).message)).not.toMatch(
+        /user|password|private|workspace|access_token|secret|fragment/,
+      );
+    }
   });
 
   it("normalizes schemeless localhost server-picker values", async () => {
diff --git a/apps/web/src/browser/browserTargetResolver.ts b/apps/web/src/browser/browserTargetResolver.ts
index 0a6dc3aa7c2..9ab7f77e84b 100644
--- a/apps/web/src/browser/browserTargetResolver.ts
+++ b/apps/web/src/browser/browserTargetResolver.ts
@@ -1,12 +1,52 @@
-import type {
-  BrowserNavigationTarget,
+import {
+  type BrowserNavigationTarget,
   EnvironmentId,
-  PreviewUrlResolution,
+  type PreviewUrlResolution,
 } from "@t3tools/contracts";
 import { isLoopbackHost, normalizePreviewUrl } from "@t3tools/shared/preview";
+import { getUrlDiagnostics } from "@t3tools/shared/urlDiagnostics";
+import * as Schema from "effect/Schema";
 
 import { readPreparedConnection } from "~/state/session";
 
+export class BrowserTargetEnvironmentDisconnectedError extends Schema.TaggedErrorClass<BrowserTargetEnvironmentDisconnectedError>()(
+  "BrowserTargetEnvironmentDisconnectedError",
+  {
+    environmentId: EnvironmentId,
+  },
+) {
+  override get message(): string {
+    return `Environment ${this.environmentId} is not connected.`;
+  }
+}
+
+export class BrowserTargetEnvironmentUrlInvalidError extends Schema.TaggedErrorClass<BrowserTargetEnvironmentUrlInvalidError>()(
+  "BrowserTargetEnvironmentUrlInvalidError",
+  {
+    environmentId: EnvironmentId,
+    httpBaseUrlInputLength: Schema.Number,
+    httpBaseUrlProtocol: Schema.optionalKey(Schema.String),
+    httpBaseUrlHostname: Schema.optionalKey(Schema.String),
+    cause: Schema.Defect(),
+  },
+) {
+  override get message(): string {
+    return `Environment ${this.environmentId} has an invalid HTTP base URL input of length ${this.httpBaseUrlInputLength}.`;
+  }
+}
+
+export class BrowserTargetPrivateNetworkRequiredError extends Schema.TaggedErrorClass<BrowserTargetPrivateNetworkRequiredError>()(
+  "BrowserTargetPrivateNetworkRequiredError",
+  {
+    environmentId: EnvironmentId,
+    hostname: Schema.String,
+  },
+) {
+  override get message(): string {
+    return `Environment ${this.environmentId} host ${this.hostname} needs the planned authenticated preview gateway because it is not directly private-network reachable.`;
+  }
+}
+
 const isPrivateNetworkHost = (host: string): boolean => {
   const normalized = host.toLowerCase().replace(/^\[|\]$/g, "");
   if (normalized === "localhost" || normalized === "::1" || normalized.endsWith(".local")) {
@@ -37,12 +77,27 @@ export function resolveBrowserNavigationTarget(
     };
   }
   const connection = readPreparedConnection(environmentId);
-  if (!connection) throw new Error(`Environment ${environmentId} is not connected.`);
-  const environmentUrl = new URL(connection.httpBaseUrl);
+  if (!connection) {
+    throw new BrowserTargetEnvironmentDisconnectedError({ environmentId });
+  }
+  let environmentUrl: URL;
+  try {
+    environmentUrl = new URL(connection.httpBaseUrl);
+  } catch (cause) {
+    const diagnostics = getUrlDiagnostics(connection.httpBaseUrl);
+    throw new BrowserTargetEnvironmentUrlInvalidError({
+      environmentId,
+      httpBaseUrlInputLength: diagnostics.inputLength,
+      ...(diagnostics.protocol === undefined ? {} : { httpBaseUrlProtocol: diagnostics.protocol }),
+      ...(diagnostics.hostname === undefined ? {} : { httpBaseUrlHostname: diagnostics.hostname }),
+      cause,
+    });
+  }
   if (!isPrivateNetworkHost(environmentUrl.hostname)) {
-    throw new Error(
-      "This environment port needs the planned authenticated preview gateway; its server address is not directly private-network reachable.",
-    );
+    throw new BrowserTargetPrivateNetworkRequiredError({
+      environmentId,
+      hostname: environmentUrl.hostname,
+    });
   }
   const protocol = target.protocol ?? "http";
   const path = target.path?.startsWith("/") ? target.path : `/${target.path ?? ""}`;
diff --git a/apps/web/src/cloud/dpop.test.ts b/apps/web/src/cloud/dpop.test.ts
index 75951db1baf..82b49be1406 100644
--- a/apps/web/src/cloud/dpop.test.ts
+++ b/apps/web/src/cloud/dpop.test.ts
@@ -1,10 +1,17 @@
 import { verifyDpopProof } from "@t3tools/shared/dpop";
 import { describe, expect, it } from "@effect/vitest";
 import * as Effect from "effect/Effect";
-import { decodeJwt } from "jose";
+import { decodeJwt, SignJWT } from "jose";
 import { vi } from "vite-plus/test";
 
-import { browserCryptoLayer, createBrowserDpopProof, generateBrowserDpopKey } from "./dpop";
+import {
+  browserCryptoLayer,
+  BrowserDpopKeyError,
+  BrowserDpopProofError,
+  createBrowserDpopProof,
+  generateBrowserDpopKey,
+  isBrowserDpopError,
+} from "./dpop";
 
 describe("browser DPoP proofs", () => {
   it.effect("signs relay resource proofs with an access-token hash", () =>
@@ -32,4 +39,80 @@ describe("browser DPoP proofs", () => {
       ).toMatchObject({ ok: true });
     }),
   );
+
+  it.effect("preserves safe invalid URL context and the parser cause", () =>
+    Effect.gen(function* () {
+      const proofKey = yield* generateBrowserDpopKey;
+      const url = "http://";
+      const error = yield* createBrowserDpopProof({
+        method: "POST",
+        url,
+        proofKey,
+      }).pipe(Effect.provide(browserCryptoLayer), Effect.flip);
+
+      expect(error).toBeInstanceOf(BrowserDpopProofError);
+      expect(error).toMatchObject({
+        operation: "normalize-url",
+        method: "POST",
+        requestTarget: "<invalid-url>",
+        urlLength: url.length,
+        thumbprint: proofKey.thumbprint,
+      });
+      expect(error).not.toHaveProperty("url");
+      expect(error).not.toHaveProperty("normalizedUrl");
+      expect(error.cause).toBeInstanceOf(Error);
+      expect(error.message).not.toContain((error.cause as Error).message);
+      expect(isBrowserDpopError(error)).toBe(true);
+    }),
+  );
+
+  it.effect("redacts URL credentials, query, and fragment from proof errors", () =>
+    Effect.gen(function* () {
+      const proofKey = yield* generateBrowserDpopKey;
+      const cause = new Error("signing failed");
+      const sign = vi.spyOn(SignJWT.prototype, "sign").mockRejectedValueOnce(cause);
+      const url = "https://user:password@example.com/oauth/token?access_token=secret#fragment";
+
+      const error = yield* createBrowserDpopProof({
+        method: "POST",
+        url,
+        proofKey,
+      }).pipe(Effect.provide(browserCryptoLayer), Effect.flip);
+
+      expect(error).toBeInstanceOf(BrowserDpopProofError);
+      expect(error).toMatchObject({
+        operation: "sign",
+        method: "POST",
+        requestTarget: "https://example.com/oauth/token",
+        urlLength: url.length,
+        thumbprint: proofKey.thumbprint,
+        cause,
+      });
+      expect(error).not.toHaveProperty("url");
+      expect(error).not.toHaveProperty("normalizedUrl");
+      expect(error.message).not.toContain("user");
+      expect(error.message).not.toContain("password");
+      expect(error.message).not.toContain("access_token");
+      expect(error.message).not.toContain("secret");
+      expect(error.message).not.toContain("fragment");
+      sign.mockRestore();
+    }),
+  );
+
+  it.effect("preserves the browser crypto cause when key generation fails", () =>
+    Effect.gen(function* () {
+      const cause = new Error("browser crypto unavailable");
+      const generateKey = vi
+        .spyOn(globalThis.crypto.subtle, "generateKey")
+        .mockRejectedValueOnce(cause);
+
+      const error = yield* generateBrowserDpopKey.pipe(Effect.flip);
+
+      expect(error).toBeInstanceOf(BrowserDpopKeyError);
+      expect(error.operation).toBe("generate");
+      expect(error.cause).toBe(cause);
+      expect(error.message).not.toContain(cause.message);
+      generateKey.mockRestore();
+    }),
+  );
 });
diff --git a/apps/web/src/cloud/dpop.ts b/apps/web/src/cloud/dpop.ts
index d0994955db1..9c4a7536048 100644
--- a/apps/web/src/cloud/dpop.ts
+++ b/apps/web/src/cloud/dpop.ts
@@ -2,9 +2,9 @@ import {
   computeDpopAccessTokenHash,
   computeDpopJwkThumbprint,
   DpopPublicJwk,
+  redactDpopRequestTarget,
 } from "@t3tools/shared/dpop";
 import * as Crypto from "effect/Crypto";
-import * as Data from "effect/Data";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as Schema from "effect/Schema";
@@ -16,10 +16,62 @@ export interface BrowserDpopKey {
   readonly thumbprint: string;
 }
 
-export class BrowserDpopError extends Data.TaggedError("BrowserDpopError")<{
-  readonly message: string;
-  readonly cause?: unknown;
-}> {}
+export class BrowserDpopStorageError extends Schema.TaggedErrorClass<BrowserDpopStorageError>()(
+  "BrowserDpopStorageError",
+  {
+    operation: Schema.Literals(["open", "read", "write"]),
+    databaseName: Schema.String,
+    storeName: Schema.String,
+    keyId: Schema.String,
+    cause: Schema.optional(Schema.Defect()),
+  },
+) {
+  override get message(): string {
+    return `Browser DPoP key storage operation "${this.operation}" failed for database "${this.databaseName}".`;
+  }
+}
+
+export class BrowserDpopKeyError extends Schema.TaggedErrorClass<BrowserDpopKeyError>()(
+  "BrowserDpopKeyError",
+  {
+    operation: Schema.Literals([
+      "generate",
+      "export-private",
+      "export-public",
+      "validate-public",
+      "import-private",
+    ]),
+    cause: Schema.Defect(),
+  },
+) {
+  override get message(): string {
+    return `Browser DPoP key operation "${this.operation}" failed.`;
+  }
+}
+
+export class BrowserDpopProofError extends Schema.TaggedErrorClass<BrowserDpopProofError>()(
+  "BrowserDpopProofError",
+  {
+    operation: Schema.Literals(["normalize-url", "generate-id", "sign"]),
+    method: Schema.String,
+    requestTarget: Schema.String,
+    urlLength: Schema.Number,
+    thumbprint: Schema.String,
+    cause: Schema.Defect(),
+  },
+) {
+  override get message(): string {
+    return `Browser DPoP proof operation "${this.operation}" failed for ${this.method.toUpperCase()} ${this.requestTarget}.`;
+  }
+}
+
+export const BrowserDpopError = Schema.Union([
+  BrowserDpopStorageError,
+  BrowserDpopKeyError,
+  BrowserDpopProofError,
+]);
+export type BrowserDpopError = typeof BrowserDpopError.Type;
+export const isBrowserDpopError = Schema.is(BrowserDpopError);
 
 const DPOP_DATABASE_NAME = "t3code:cloud-auth";
 const DPOP_DATABASE_VERSION = 1;
@@ -40,16 +92,20 @@ export const browserCryptoLayer = Layer.succeed(
   }),
 );
 
-function dpopError(message: string, cause?: unknown) {
-  return new BrowserDpopError({ message, ...(cause === undefined ? {} : { cause }) });
-}
-
 function openDpopDatabase(): Effect.Effect<IDBDatabase, BrowserDpopError> {
   return Effect.callback<IDBDatabase, BrowserDpopError>((resume) => {
     const request = indexedDB.open(DPOP_DATABASE_NAME, DPOP_DATABASE_VERSION);
     request.addEventListener("error", () =>
       resume(
-        Effect.fail(dpopError("Could not open DPoP key storage.", request.error ?? undefined)),
+        Effect.fail(
+          new BrowserDpopStorageError({
+            operation: "open",
+            databaseName: DPOP_DATABASE_NAME,
+            storeName: DPOP_KEY_STORE_NAME,
+            keyId: DPOP_KEY_ID,
+            ...(request.error === null ? {} : { cause: request.error }),
+          }),
+        ),
       ),
     );
     request.addEventListener("upgradeneeded", () => {
@@ -74,7 +130,17 @@ export function readStoredBrowserDpopKey(): Effect.Effect<BrowserDpopKey | null,
           .objectStore(DPOP_KEY_STORE_NAME)
           .get(DPOP_KEY_ID);
         request.addEventListener("error", () =>
-          resume(Effect.fail(dpopError("Could not read DPoP key.", request.error ?? undefined))),
+          resume(
+            Effect.fail(
+              new BrowserDpopStorageError({
+                operation: "read",
+                databaseName: DPOP_DATABASE_NAME,
+                storeName: DPOP_KEY_STORE_NAME,
+                keyId: DPOP_KEY_ID,
+                ...(request.error === null ? {} : { cause: request.error }),
+              }),
+            ),
+          ),
         );
         request.addEventListener("success", () =>
           resume(Effect.succeed((request.result as BrowserDpopKey | undefined) ?? null)),
@@ -97,7 +163,15 @@ export function writeStoredBrowserDpopKey(
         const transaction = database.transaction(DPOP_KEY_STORE_NAME, "readwrite");
         transaction.addEventListener("error", () =>
           resume(
-            Effect.fail(dpopError("Could not write DPoP key.", transaction.error ?? undefined)),
+            Effect.fail(
+              new BrowserDpopStorageError({
+                operation: "write",
+                databaseName: DPOP_DATABASE_NAME,
+                storeName: DPOP_KEY_STORE_NAME,
+                keyId: DPOP_KEY_ID,
+                ...(transaction.error === null ? {} : { cause: transaction.error }),
+              }),
+            ),
           ),
         );
         transaction.addEventListener("complete", () => resume(Effect.void));
@@ -114,26 +188,22 @@ export const generateBrowserDpopKey = Effect.gen(function* () {
         "sign",
         "verify",
       ]) as Promise<CryptoKeyPair>,
-    catch: (cause) => dpopError("Could not generate DPoP proof key.", cause),
+    catch: (cause) => new BrowserDpopKeyError({ operation: "generate", cause }),
   });
   const privateJwk = yield* Effect.tryPromise({
     try: () => crypto.subtle.exportKey("jwk", generated.privateKey),
-    catch: (cause) => dpopError("Could not export DPoP private key.", cause),
+    catch: (cause) => new BrowserDpopKeyError({ operation: "export-private", cause }),
   });
-  const publicJwk = yield* Effect.tryPromise({
+  const encodedPublicJwk = yield* Effect.tryPromise({
     try: () => crypto.subtle.exportKey("jwk", generated.publicKey),
-    catch: (cause) => dpopError("Could not export DPoP public key.", cause),
-  }).pipe(
-    Effect.flatMap((jwk) => decodeDpopPublicJwk(jwk)),
-    Effect.mapError((cause) =>
-      cause instanceof BrowserDpopError
-        ? cause
-        : dpopError("Generated DPoP public key is invalid.", cause),
-    ),
+    catch: (cause) => new BrowserDpopKeyError({ operation: "export-public", cause }),
+  });
+  const publicJwk = yield* decodeDpopPublicJwk(encodedPublicJwk).pipe(
+    Effect.mapError((cause) => new BrowserDpopKeyError({ operation: "validate-public", cause })),
   );
   const privateKey = yield* Effect.tryPromise({
     try: () => importJWK(privateJwk as JWK, "ES256", { extractable: false }) as Promise<CryptoKey>,
-    catch: (cause) => dpopError("Could not import DPoP private key.", cause),
+    catch: (cause) => new BrowserDpopKeyError({ operation: "import-private", cause }),
   });
   return {
     privateKey,
@@ -153,15 +223,35 @@ export function createBrowserDpopProof(input: {
   Crypto.Crypto
 > {
   return Effect.gen(function* () {
+    const requestTarget = redactDpopRequestTarget(input.url);
+    const urlLength = input.url.length;
     const normalizedUrl = yield* Effect.try({
       try: () => new URL(input.url),
-      catch: (cause) => dpopError("Could not normalize DPoP proof URL.", cause),
+      catch: (cause) =>
+        new BrowserDpopProofError({
+          operation: "normalize-url",
+          method: input.method,
+          requestTarget,
+          urlLength,
+          thumbprint: input.proofKey.thumbprint,
+          cause,
+        }),
     });
     normalizedUrl.search = "";
     normalizedUrl.hash = "";
     const jti = yield* Crypto.Crypto.pipe(
       Effect.flatMap((crypto) => crypto.randomUUIDv4),
-      Effect.mapError((cause) => dpopError("Could not generate DPoP proof identifier.", cause)),
+      Effect.mapError(
+        (cause) =>
+          new BrowserDpopProofError({
+            operation: "generate-id",
+            method: input.method,
+            requestTarget,
+            urlLength,
+            thumbprint: input.proofKey.thumbprint,
+            cause,
+          }),
+      ),
     );
     const proof = yield* Effect.tryPromise({
       try: () =>
@@ -178,7 +268,15 @@ export function createBrowserDpopProof(input: {
           })
           .setIssuedAt()
           .sign(input.proofKey.privateKey),
-      catch: (cause) => dpopError("Could not sign DPoP proof.", cause),
+      catch: (cause) =>
+        new BrowserDpopProofError({
+          operation: "sign",
+          method: input.method,
+          requestTarget,
+          urlLength,
+          thumbprint: input.proofKey.thumbprint,
+          cause,
+        }),
     });
     return { proof, thumbprint: input.proofKey.thumbprint };
   });
diff --git a/apps/web/src/cloud/linkEnvironment.test.ts b/apps/web/src/cloud/linkEnvironment.test.ts
index f823016ddf0..88497ed3707 100644
--- a/apps/web/src/cloud/linkEnvironment.test.ts
+++ b/apps/web/src/cloud/linkEnvironment.test.ts
@@ -2,12 +2,14 @@ import {
   type DesktopBridge,
   EnvironmentId,
   type RelayClientInstallProgressEvent,
+  type RelayClientStatus,
   WS_METHODS,
 } from "@t3tools/contracts";
 import { RelayWebClientId } from "@t3tools/contracts/relay";
 import { describe, expect, it } from "@effect/vitest";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
+import * as Logger from "effect/Logger";
 import * as Option from "effect/Option";
 import * as Stream from "effect/Stream";
 import * as SubscriptionRef from "effect/SubscriptionRef";
@@ -26,7 +28,9 @@ import { remoteHttpClientLayer } from "@t3tools/client-runtime/rpc";
 import { __resetDesktopPrimaryAuthForTests } from "../environments/primary/desktopAuth";
 
 import {
+  CloudEnvironmentLinkOperationError,
   collectCloudLinkTargets,
+  isCloudEnvironmentLinkError,
   linkPrimaryEnvironmentToCloud,
   listManagedCloudEnvironments,
   normalizeRelayBaseUrl,
@@ -48,12 +52,21 @@ const relayClientInstallDialog = vi.hoisted(() => ({
   finish: vi.fn(),
 }));
 
+const cloudPublicConfig = vi.hoisted(() => ({
+  relayUrl: "https://relay.example.test",
+}));
+
 vi.mock("./relayClientInstallDialog", () => ({
   requestRelayClientInstallConfirmation: relayClientInstallDialog.requestConfirmation,
   reportRelayClientInstallProgress: relayClientInstallDialog.reportProgress,
   finishRelayClientInstall: relayClientInstallDialog.finish,
 }));
 
+vi.mock("./publicConfig", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("./publicConfig")>()),
+  resolveCloudPublicConfig: () => ({ relayUrl: cloudPublicConfig.relayUrl }),
+}));
+
 const createProof = vi.fn(() => Effect.succeed("dpop-proof"));
 const dpopSignerLayer = Layer.succeed(
   ManagedRelay.ManagedRelayDpopSigner,
@@ -75,7 +88,7 @@ function relayLayer() {
 }
 
 function registryLayer(options?: {
-  readonly status?: { readonly status: "available"; readonly version: string };
+  readonly status?: RelayClientStatus;
   readonly installEvents?: ReadonlyArray<RelayClientInstallProgressEvent>;
 }) {
   return Layer.effect(
@@ -83,7 +96,14 @@ function registryLayer(options?: {
     Effect.gen(function* () {
       const client = {
         [WS_METHODS.cloudGetRelayClientStatus]: () =>
-          Effect.succeed(options?.status ?? { status: "available", version: "2026.6.0" }),
+          Effect.succeed(
+            options?.status ?? {
+              status: "available",
+              executablePath: "/managed/cloudflared",
+              source: "managed",
+              version: "2026.6.0",
+            },
+          ),
         [WS_METHODS.cloudInstallRelayClient]: () =>
           Stream.fromIterable(options?.installEvents ?? []),
       } as unknown as RpcSession["client"];
@@ -141,6 +161,7 @@ function bodyText(body: BodyInit | null | undefined): string {
 
 beforeEach(() => {
   vi.clearAllMocks();
+  cloudPublicConfig.relayUrl = "https://relay.example.test";
   vi.stubEnv("VITE_T3CODE_RELAY_URL", "https://relay.example.test");
   relayClientInstallDialog.requestConfirmation.mockResolvedValue(true);
 });
@@ -195,6 +216,47 @@ describe("web cloud link environment client", () => {
     }),
   );
 
+  it.effect("preserves structured relay failures and trace IDs", () =>
+    Effect.gen(function* () {
+      vi.stubGlobal(
+        "fetch",
+        vi.fn().mockResolvedValue(
+          Response.json(
+            {
+              _tag: "RelayAuthInvalidError",
+              code: "auth_invalid",
+              reason: "invalid_bearer",
+              traceId: "trace-web-cloud-link",
+            },
+            { status: 401 },
+          ),
+        ),
+      );
+
+      const error = yield* withServices(
+        listManagedCloudEnvironments({ clerkToken: "clerk-token" }),
+      ).pipe(Effect.flip);
+
+      expect(error).toBeInstanceOf(CloudEnvironmentLinkOperationError);
+      expect(error).toMatchObject({
+        action: "list relay-managed environments",
+        relayUrlInputLength: "https://relay.example.test".length,
+        relayUrlProtocol: "https:",
+        relayUrlHostname: "relay.example.test",
+        traceId: "trace-web-cloud-link",
+        relayError: {
+          _tag: "RelayAuthInvalidError",
+          reason: "invalid_bearer",
+        },
+        cause: {
+          _tag: "ManagedRelayRequestFailedError",
+        },
+      });
+      expect(error.message).toBe("Could not list relay-managed environments.");
+      expect(isCloudEnvironmentLinkError(error)).toBe(true);
+    }),
+  );
+
   it.effect("reads primary cloud link state from the explicit target", () =>
     Effect.gen(function* () {
       const fetchMock = vi.fn().mockResolvedValue(
@@ -225,6 +287,96 @@ describe("web cloud link environment client", () => {
     }),
   );
 
+  it.effect("preserves structured environment API failures and their cause chain", () =>
+    Effect.gen(function* () {
+      vi.stubGlobal(
+        "fetch",
+        vi.fn().mockResolvedValue(
+          Response.json(
+            {
+              _tag: "EnvironmentHttpUnauthorizedError",
+              message: "Environment bearer token is invalid.",
+            },
+            { status: 401 },
+          ),
+        ),
+      );
+
+      const error = yield* withServices(readPrimaryCloudLinkState({ target: TARGET })).pipe(
+        Effect.flip,
+      );
+
+      expect(error).toBeInstanceOf(CloudEnvironmentLinkOperationError);
+      expect(error).toMatchObject({
+        action: "read environment cloud link state",
+        environmentId: TARGET.environmentId,
+        httpBaseUrlInputLength: TARGET.httpBaseUrl.length,
+        httpBaseUrlProtocol: "http:",
+        httpBaseUrlHostname: "127.0.0.1",
+        environmentError: {
+          _tag: "EnvironmentHttpUnauthorizedError",
+          message: "Environment bearer token is invalid.",
+        },
+      });
+      expect(error.cause).toBeDefined();
+      expect(error.message).toBe(
+        `Could not read environment cloud link state for environment "${TARGET.environmentId}".`,
+      );
+      expect(isCloudEnvironmentLinkError(error)).toBe(true);
+    }),
+  );
+
+  it.effect("preserves invalid environment HTTP URL parser causes", () =>
+    Effect.gen(function* () {
+      const invalidUrl =
+        "https://user:password@[invalid-host]/private/path?access_token=secret#fragment";
+      const error = yield* withServices(
+        readPrimaryCloudLinkState({
+          target: {
+            ...TARGET,
+            httpBaseUrl: invalidUrl,
+          },
+        }),
+      ).pipe(Effect.flip);
+
+      expect(error).toMatchObject({
+        _tag: "CloudEnvironmentLinkOperationError",
+        action: "initialize the environment HTTP client",
+        environmentId: TARGET.environmentId,
+        httpBaseUrlInputLength: invalidUrl.length,
+      });
+      expect(error.cause).toBeInstanceOf(TypeError);
+      expect(error).not.toHaveProperty("httpBaseUrl");
+      expect(error).not.toHaveProperty("httpBaseUrlProtocol");
+      expect(error).not.toHaveProperty("httpBaseUrlHostname");
+      expect(error.message).not.toMatch(/user|password|private|path|access_token|secret|fragment/);
+    }),
+  );
+
+  it("keeps environment endpoint secrets out of mapped error attributes", () => {
+    const httpBaseUrl =
+      "https://user:password@environment.example.test/private/path?access_token=secret#fragment";
+    const cause = new Error("request failed");
+    const error = CloudEnvironmentLinkOperationError.fromEnvironmentApi({
+      action: "read environment cloud link state",
+      environmentId: TARGET.environmentId,
+      httpBaseUrl,
+      cause,
+    });
+
+    expect(error).toMatchObject({
+      httpBaseUrlInputLength: httpBaseUrl.length,
+      httpBaseUrlProtocol: "https:",
+      httpBaseUrlHostname: "environment.example.test",
+      cause,
+    });
+    expect(error.cause).toBe(cause);
+    expect(error).not.toHaveProperty("httpBaseUrl");
+    const diagnostics = JSON.stringify(error);
+    expect(diagnostics).not.toMatch(/user|password|private|path|access_token|secret|fragment/);
+    expect(error.message).not.toMatch(/user|password|private|path|access_token|secret|fragment/);
+  });
+
   it.effect("uses desktop bearer auth for primary cloud link state", () =>
     Effect.gen(function* () {
       const fetchMock = vi.fn().mockResolvedValue(
@@ -306,6 +458,37 @@ describe("web cloud link environment client", () => {
     }),
   );
 
+  it.effect("validates the environment endpoint before prompting to install a relay client", () =>
+    Effect.gen(function* () {
+      const invalidUrl =
+        "https://user:password@[invalid-host]/private/path?access_token=secret#fragment";
+
+      const error = yield* withServices(
+        linkPrimaryEnvironmentToCloud({
+          target: {
+            ...TARGET,
+            httpBaseUrl: invalidUrl,
+          },
+          clerkToken: "clerk-token",
+        }),
+        {
+          status: { status: "missing", version: "2026.6.0" },
+        },
+      ).pipe(Effect.flip);
+
+      expect(error).toMatchObject({
+        _tag: "CloudEnvironmentLinkOperationError",
+        action: "derive the environment endpoint origin",
+        environmentId: TARGET.environmentId,
+        httpBaseUrlInputLength: invalidUrl.length,
+      });
+      expect(error.cause).toBeInstanceOf(TypeError);
+      expect(error).not.toHaveProperty("httpBaseUrl");
+      expect(error.message).not.toMatch(/user|password|private|path|access_token|secret|fragment/);
+      expect(relayClientInstallDialog.requestConfirmation).not.toHaveBeenCalled();
+    }),
+  );
+
   it.effect("installs a missing relay client before linking", () =>
     Effect.gen(function* () {
       vi.stubGlobal("fetch", vi.fn().mockResolvedValue(Response.json({ malformed: true })));
@@ -316,7 +499,12 @@ describe("web cloud link environment client", () => {
           clerkToken: "clerk-token",
         }),
         {
-          status: { status: "available", version: "2026.6.0" },
+          status: {
+            status: "available",
+            executablePath: "/managed/cloudflared",
+            source: "managed",
+            version: "2026.6.0",
+          },
           installEvents: [],
         },
       ).pipe(Effect.flip);
@@ -348,4 +536,64 @@ describe("web cloud link environment client", () => {
       );
     }),
   );
+
+  it.effect("keeps configured relay URL secrets out of revoke warnings", () => {
+    const relayUrl =
+      "https://relay-user:relay-password@relay.example.test/private/workspace?access_token=relay-secret#relay-fragment";
+    cloudPublicConfig.relayUrl = relayUrl;
+    const capturedLogs: Array<ReadonlyArray<unknown>> = [];
+    const logger = Logger.make(({ message }) => {
+      capturedLogs.push(Array.isArray(message) ? message : [message]);
+    });
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValueOnce(
+        Response.json({ ok: true, endpointRuntimeStatus: { status: "disabled" } }),
+      )
+      .mockResolvedValueOnce(Response.json({ malformed: true }, { status: 500 }));
+    vi.stubGlobal("fetch", fetchMock);
+
+    return unlinkPrimaryEnvironmentFromCloud({
+      target: TARGET,
+      clerkToken: "clerk-token",
+    }).pipe(
+      Effect.provide(
+        Layer.merge(
+          services(),
+          Logger.layer([logger], {
+            mergeWithExisting: false,
+          }),
+        ),
+      ),
+      Effect.tap(() =>
+        Effect.sync(() => {
+          expect(capturedLogs).toHaveLength(1);
+          const logFields = capturedLogs[0]?.find(
+            (value): value is Record<string, unknown> =>
+              typeof value === "object" && value !== null,
+          );
+          expect(logFields).toMatchObject({
+            relayUrlInputLength: relayUrl.length,
+            relayUrlProtocol: "https:",
+            relayUrlHostname: "relay.example.test",
+            causeTag: "ManagedRelayRequestFailedError",
+          });
+          expect(logFields).not.toHaveProperty("relayUrl");
+          expect(logFields).not.toHaveProperty("cause");
+          const logText = capturedLogs[0]
+            ?.filter((value): value is string => typeof value === "string")
+            .join(" ");
+          for (const secret of [
+            "relay-user",
+            "relay-password",
+            "/private/workspace",
+            "access_token=relay-secret",
+            "relay-fragment",
+          ]) {
+            expect(logText).not.toContain(secret);
+          }
+        }),
+      ),
+    );
+  });
 });
diff --git a/apps/web/src/cloud/linkEnvironment.ts b/apps/web/src/cloud/linkEnvironment.ts
index 20bf75c7d6d..9030ac3d3ec 100644
--- a/apps/web/src/cloud/linkEnvironment.ts
+++ b/apps/web/src/cloud/linkEnvironment.ts
@@ -1,4 +1,3 @@
-import * as Data from "effect/Data";
 import * as Effect from "effect/Effect";
 import * as Option from "effect/Option";
 import * as Schema from "effect/Schema";
@@ -19,13 +18,14 @@ import {
   type RelayClientDeviceRecord,
   type RelayClientEnvironmentRecord,
   type RelayEnvironmentLinkResponse,
-  type RelayProtectedError as RelayProtectedErrorType,
   type RelayManagedEndpointProviderKind,
+  RelayProtectedError,
 } from "@t3tools/contracts/relay";
 import { EnvironmentRegistry } from "@t3tools/client-runtime/connection";
 import { request, runStream } from "@t3tools/client-runtime/rpc";
 import { makeEnvironmentHttpApiClient } from "@t3tools/client-runtime/rpc";
 import { ManagedRelay } from "@t3tools/client-runtime/relay";
+import { getUrlDiagnostics } from "@t3tools/shared/urlDiagnostics";
 
 import {
   readPrimaryEnvironmentDescriptor,
@@ -51,17 +51,218 @@ function relayUrl(): string | null {
   return resolveCloudPublicConfig().relayUrl;
 }
 
-export class CloudEnvironmentLinkError extends Data.TaggedError("CloudEnvironmentLinkError")<{
-  readonly message: string;
-  readonly cause?: unknown;
-  readonly traceId?: string;
-}> {}
+const EnvironmentCloudApiError = Schema.Union([
+  EnvironmentHttpBadRequestError,
+  EnvironmentHttpUnauthorizedError,
+  EnvironmentHttpForbiddenError,
+  EnvironmentHttpConflictError,
+  EnvironmentHttpInternalServerError,
+  EnvironmentCloudEndpointUnavailableError,
+]);
+type EnvironmentCloudApiError = typeof EnvironmentCloudApiError.Type;
+const isEnvironmentCloudApiError = Schema.is(EnvironmentCloudApiError);
 
-const relayClientRpcError = (message: string) => (cause: unknown) =>
-  new CloudEnvironmentLinkError({
-    message,
-    cause,
-  });
+function relayUrlDiagnosticFields(relayUrl: string | undefined) {
+  if (relayUrl === undefined) return {};
+  const diagnostics = getUrlDiagnostics(relayUrl);
+  return {
+    relayUrlInputLength: diagnostics.inputLength,
+    ...(diagnostics.protocol === undefined ? {} : { relayUrlProtocol: diagnostics.protocol }),
+    ...(diagnostics.hostname === undefined ? {} : { relayUrlHostname: diagnostics.hostname }),
+  };
+}
+
+function httpBaseUrlDiagnosticFields(httpBaseUrl: string | undefined) {
+  if (httpBaseUrl === undefined) return {};
+  const diagnostics = getUrlDiagnostics(httpBaseUrl);
+  return {
+    httpBaseUrlInputLength: diagnostics.inputLength,
+    ...(diagnostics.protocol === undefined ? {} : { httpBaseUrlProtocol: diagnostics.protocol }),
+    ...(diagnostics.hostname === undefined ? {} : { httpBaseUrlHostname: diagnostics.hostname }),
+  };
+}
+
+export const CloudEnvironmentLinkAction = Schema.Literals([
+  "check relay client availability",
+  "confirm relay client installation",
+  "install the relay client",
+  "list relay-managed environments",
+  "list cloud devices",
+  "read environment cloud link state",
+  "update environment cloud preferences",
+  "unlink the environment from cloud",
+  "revoke the cloud environment link",
+  "create an environment link challenge",
+  "obtain an environment link proof",
+  "link the environment",
+  "derive the environment endpoint origin",
+  "initialize the environment HTTP client",
+  "configure environment relay access",
+]);
+export type CloudEnvironmentLinkAction = typeof CloudEnvironmentLinkAction.Type;
+
+export class CloudEnvironmentLinkOperationError extends Schema.TaggedErrorClass<CloudEnvironmentLinkOperationError>()(
+  "CloudEnvironmentLinkOperationError",
+  {
+    action: CloudEnvironmentLinkAction,
+    environmentId: Schema.optionalKey(Schema.String),
+    relayUrlInputLength: Schema.optionalKey(Schema.Number),
+    relayUrlProtocol: Schema.optionalKey(Schema.String),
+    relayUrlHostname: Schema.optionalKey(Schema.String),
+    httpBaseUrlInputLength: Schema.optionalKey(Schema.Number),
+    httpBaseUrlProtocol: Schema.optionalKey(Schema.String),
+    httpBaseUrlHostname: Schema.optionalKey(Schema.String),
+    traceId: Schema.optionalKey(Schema.String),
+    relayError: Schema.optionalKey(RelayProtectedError),
+    environmentError: Schema.optionalKey(EnvironmentCloudApiError),
+    cause: Schema.Defect(),
+  },
+) {
+  static fromManagedRelay(input: {
+    readonly action: CloudEnvironmentLinkAction;
+    readonly cause: ManagedRelay.ManagedRelayClientError;
+    readonly environmentId?: string;
+    readonly relayUrl?: string;
+    readonly httpBaseUrl?: string;
+  }): CloudEnvironmentLinkOperationError {
+    const requestFailure =
+      input.cause._tag === "ManagedRelayRequestFailedError" ? input.cause : undefined;
+    return new CloudEnvironmentLinkOperationError({
+      action: input.action,
+      cause: input.cause,
+      ...(input.environmentId === undefined ? {} : { environmentId: input.environmentId }),
+      ...relayUrlDiagnosticFields(input.relayUrl),
+      ...httpBaseUrlDiagnosticFields(input.httpBaseUrl),
+      ...(requestFailure?.traceId === undefined ? {} : { traceId: requestFailure.traceId }),
+      ...(requestFailure?.relayError === undefined
+        ? {}
+        : { relayError: requestFailure.relayError }),
+    });
+  }
+
+  static fromEnvironmentApi(input: {
+    readonly action: CloudEnvironmentLinkAction;
+    readonly cause: unknown;
+    readonly environmentId: string;
+    readonly httpBaseUrl: string;
+  }): CloudEnvironmentLinkOperationError {
+    const environmentError = CloudEnvironmentLinkOperationError.findEnvironmentApiError(
+      input.cause,
+    );
+    return new CloudEnvironmentLinkOperationError({
+      action: input.action,
+      environmentId: input.environmentId,
+      ...httpBaseUrlDiagnosticFields(input.httpBaseUrl),
+      cause: input.cause,
+      ...(environmentError === undefined ? {} : { environmentError }),
+    });
+  }
+
+  private static findEnvironmentApiError(cause: unknown): EnvironmentCloudApiError | undefined {
+    const seen = new Set<unknown>();
+    let current = cause;
+    while (typeof current === "object" && current !== null && !seen.has(current)) {
+      if (isEnvironmentCloudApiError(current)) {
+        return current;
+      }
+      seen.add(current);
+      current = "cause" in current ? current.cause : undefined;
+    }
+    return undefined;
+  }
+
+  override get message(): string {
+    const environment =
+      this.environmentId === undefined ? "" : ` for environment "${this.environmentId}"`;
+    return `Could not ${this.action}${environment}.`;
+  }
+}
+
+export class CloudRelayUrlNotConfiguredError extends Schema.TaggedErrorClass<CloudRelayUrlNotConfiguredError>()(
+  "CloudRelayUrlNotConfiguredError",
+  { environmentId: Schema.optionalKey(Schema.String) },
+) {
+  override get message(): string {
+    return "T3CODE_RELAY_URL is not configured.";
+  }
+}
+
+export class CloudRelayClientInstallUnsupportedError extends Schema.TaggedErrorClass<CloudRelayClientInstallUnsupportedError>()(
+  "CloudRelayClientInstallUnsupportedError",
+  {
+    environmentId: Schema.String,
+    phase: Schema.Literals(["preflight", "post-install"]),
+    version: Schema.String,
+    platform: Schema.String,
+    architecture: Schema.String,
+  },
+) {
+  override get message(): string {
+    return `T3 Code cannot install the relay client automatically on ${this.platform}-${this.architecture}.`;
+  }
+}
+
+export class CloudRelayClientInstallCancelledError extends Schema.TaggedErrorClass<CloudRelayClientInstallCancelledError>()(
+  "CloudRelayClientInstallCancelledError",
+  {
+    environmentId: Schema.String,
+    version: Schema.String,
+  },
+) {
+  override get message(): string {
+    return "Relay client installation was cancelled.";
+  }
+}
+
+export class CloudRelayClientInstallIncompleteError extends Schema.TaggedErrorClass<CloudRelayClientInstallIncompleteError>()(
+  "CloudRelayClientInstallIncompleteError",
+  {
+    environmentId: Schema.String,
+    version: Schema.String,
+  },
+) {
+  override get message(): string {
+    return "The relay client install completed without a final status.";
+  }
+}
+
+export class CloudRelayClientUnavailableAfterInstallError extends Schema.TaggedErrorClass<CloudRelayClientUnavailableAfterInstallError>()(
+  "CloudRelayClientUnavailableAfterInstallError",
+  {
+    environmentId: Schema.String,
+    version: Schema.String,
+  },
+) {
+  override get message(): string {
+    return "The relay client is still unavailable after installation.";
+  }
+}
+
+export class CloudEnvironmentLinkResponseMismatchError extends Schema.TaggedErrorClass<CloudEnvironmentLinkResponseMismatchError>()(
+  "CloudEnvironmentLinkResponseMismatchError",
+  {
+    environmentId: Schema.String,
+    field: Schema.Literals(["environment id", "endpoint provider"]),
+    expected: Schema.String,
+    actual: Schema.String,
+  },
+) {
+  override get message(): string {
+    return `Relay returned link credentials with an unexpected ${this.field}.`;
+  }
+}
+
+export const CloudEnvironmentLinkError = Schema.Union([
+  CloudEnvironmentLinkOperationError,
+  CloudRelayUrlNotConfiguredError,
+  CloudRelayClientInstallUnsupportedError,
+  CloudRelayClientInstallCancelledError,
+  CloudRelayClientInstallIncompleteError,
+  CloudRelayClientUnavailableAfterInstallError,
+  CloudEnvironmentLinkResponseMismatchError,
+]);
+export type CloudEnvironmentLinkError = typeof CloudEnvironmentLinkError.Type;
+export const isCloudEnvironmentLinkError = Schema.is(CloudEnvironmentLinkError);
 
 function ensureRelayClientAvailable(
   environmentId: EnvironmentId,
@@ -70,21 +271,40 @@ function ensureRelayClientAvailable(
     const registry = yield* EnvironmentRegistry;
     const status = yield* registry
       .run(environmentId, request(WS_METHODS.cloudGetRelayClientStatus, {}))
-      .pipe(Effect.mapError(relayClientRpcError("Could not check relay client availability.")));
+      .pipe(
+        Effect.mapError(
+          (cause) =>
+            new CloudEnvironmentLinkOperationError({
+              action: "check relay client availability",
+              environmentId,
+              cause,
+            }),
+        ),
+      );
     if (status.status === "available") return;
     if (status.status === "unsupported") {
-      return yield* new CloudEnvironmentLinkError({
-        message: `T3 Code cannot install the relay client automatically on ${status.platform}-${status.arch}.`,
+      return yield* new CloudRelayClientInstallUnsupportedError({
+        environmentId,
+        phase: "preflight",
+        version: status.version,
+        platform: status.platform,
+        architecture: status.arch,
       });
     }
 
     const confirmed = yield* Effect.tryPromise({
       try: () => requestRelayClientInstallConfirmation(status.version),
-      catch: relayClientRpcError("Could not confirm relay client installation."),
+      catch: (cause) =>
+        new CloudEnvironmentLinkOperationError({
+          action: "confirm relay client installation",
+          environmentId,
+          cause,
+        }),
     });
     if (!confirmed) {
-      return yield* new CloudEnvironmentLinkError({
-        message: "Relay client installation was cancelled.",
+      return yield* new CloudRelayClientInstallCancelledError({
+        environmentId,
+        version: status.version,
       });
     }
 
@@ -97,112 +317,73 @@ function ensureRelayClientAvailable(
       )
       .pipe(
         Stream.runLast,
-        Effect.mapError(relayClientRpcError("Could not install the relay client.")),
+        Effect.mapError(
+          (cause) =>
+            new CloudEnvironmentLinkOperationError({
+              action: "install the relay client",
+              environmentId,
+              cause,
+            }),
+        ),
         Effect.ensuring(Effect.sync(finishRelayClientInstall)),
       );
     if (Option.isNone(installed) || installed.value.type !== "complete") {
-      return yield* new CloudEnvironmentLinkError({
-        message: "The relay client install completed without a final status.",
+      return yield* new CloudRelayClientInstallIncompleteError({
+        environmentId,
+        version: status.version,
       });
     }
     const installedStatus = installed.value.status;
     if (installedStatus.status !== "available") {
-      return yield* new CloudEnvironmentLinkError({
-        message:
-          installedStatus.status === "unsupported"
-            ? `T3 Code cannot install the relay client automatically on ${installedStatus.platform}-${installedStatus.arch}.`
-            : "The relay client is still unavailable after installation.",
-      });
+      return yield* installedStatus.status === "unsupported"
+        ? new CloudRelayClientInstallUnsupportedError({
+            environmentId,
+            phase: "post-install",
+            version: installedStatus.version,
+            platform: installedStatus.platform,
+            architecture: installedStatus.arch,
+          })
+        : new CloudRelayClientUnavailableAfterInstallError({
+            environmentId,
+            version: installedStatus.version,
+          });
     }
   });
 }
 
-const isEnvironmentCloudApiError = Schema.is(
-  Schema.Union([
-    EnvironmentHttpBadRequestError,
-    EnvironmentHttpUnauthorizedError,
-    EnvironmentHttpForbiddenError,
-    EnvironmentHttpConflictError,
-    EnvironmentHttpInternalServerError,
-    EnvironmentCloudEndpointUnavailableError,
-  ]),
-);
-
-function relayProtectedErrorMessage(error: RelayProtectedErrorType): string {
-  switch (error._tag) {
-    case "RelayAuthInvalidError":
-      switch (error.reason) {
-        case "missing_bearer":
-        case "invalid_bearer":
-          return "Relay rejected the cloud session token.";
-        case "invalid_dpop":
-          return "Relay rejected the DPoP proof.";
-        case "not_authorized":
-          return "Relay rejected the authenticated request.";
-      }
-    case "RelayEnvironmentLinkProofExpiredError":
-      return "Relay rejected an expired environment link proof.";
-    case "RelayEnvironmentLinkProofInvalidError":
-      return `Relay rejected the environment link proof (${error.reason}).`;
-    case "RelayEnvironmentConnectNotAuthorizedError":
-      return "Relay rejected the environment connection request.";
-    case "RelayEnvironmentEndpointUnavailableError":
-      return `Relay could not reach the environment endpoint (${error.reason}).`;
-    case "RelayEnvironmentEndpointTimedOutError":
-      return "Relay timed out while contacting the environment endpoint.";
-    case "RelayEnvironmentLinkFailedError":
-      return `Relay could not link the environment (${error.reason}).`;
-    case "RelayEnvironmentLinkUnavailableError":
-      return `Relay cannot provision the managed endpoint (${error.reason}).`;
-    case "RelayAgentActivityPublishProofExpiredError":
-      return "Relay rejected an expired agent activity publish proof.";
-    case "RelayAgentActivityPublishProofInvalidError":
-      return `Relay rejected the agent activity publish proof (${error.reason}).`;
-    case "RelayInternalError":
-      return `Relay encountered an internal error (${error.reason}).`;
-  }
-}
-
-function decodedRelayClientError(message: string) {
-  return (cause: ManagedRelay.ManagedRelayClientError) => {
-    const relayError =
-      cause._tag === "ManagedRelayRequestFailedError" ? cause.relayError : undefined;
-    const traceId = cause._tag === "ManagedRelayRequestFailedError" ? cause.traceId : undefined;
-    const detail = relayError ? relayProtectedErrorMessage(relayError) : null;
-    return new CloudEnvironmentLinkError({
-      message: detail ? `${message}: ${detail}` : message,
-      cause,
-      ...(traceId ? { traceId } : {}),
-    });
-  };
-}
-
-function findEnvironmentCloudApiError(cause: unknown): { readonly message: string } | null {
-  if (isEnvironmentCloudApiError(cause)) {
-    return cause;
-  }
-  if (typeof cause !== "object" || cause === null) {
-    return null;
-  }
-  return "cause" in cause ? findEnvironmentCloudApiError(cause.cause) : null;
-}
-
-const environmentApiError = (message: string) => (cause: unknown) => {
-  const environmentError = findEnvironmentCloudApiError(cause);
-  return new CloudEnvironmentLinkError({
-    message: environmentError
-      ? `${message.replace(/[.:]$/, "")}: ${environmentError.message}`
-      : message,
-    cause,
+function endpointOrigin(input: { readonly environmentId: string; readonly httpBaseUrl: string }) {
+  return Effect.try({
+    try: () => {
+      const url = new URL(input.httpBaseUrl);
+      return {
+        localHttpHost: "127.0.0.1",
+        localHttpPort: Number(url.port || (url.protocol === "https:" ? 443 : 80)),
+      };
+    },
+    catch: (cause) =>
+      new CloudEnvironmentLinkOperationError({
+        action: "derive the environment endpoint origin",
+        environmentId: input.environmentId,
+        ...httpBaseUrlDiagnosticFields(input.httpBaseUrl),
+        cause,
+      }),
   });
-};
+}
 
-function endpointOrigin(httpBaseUrl: string) {
-  const url = new URL(httpBaseUrl);
-  return {
-    localHttpHost: "127.0.0.1",
-    localHttpPort: Number(url.port || (url.protocol === "https:" ? 443 : 80)),
-  };
+function makeCloudEnvironmentHttpApiClient(input: {
+  readonly environmentId: string;
+  readonly httpBaseUrl: string;
+}) {
+  return Effect.try({
+    try: () => makeEnvironmentHttpApiClient(input.httpBaseUrl),
+    catch: (cause) =>
+      new CloudEnvironmentLinkOperationError({
+        action: "initialize the environment HTTP client",
+        environmentId: input.environmentId,
+        ...httpBaseUrlDiagnosticFields(input.httpBaseUrl),
+        cause,
+      }),
+  }).pipe(Effect.flatten);
 }
 
 const MANAGED_ENDPOINT_PROVIDER_KIND =
@@ -214,13 +395,19 @@ function ensureLinkedEnvironmentMatches(input: {
   readonly link: RelayEnvironmentLinkResponse;
 }): Effect.Effect<void, CloudEnvironmentLinkError> {
   if (input.link.environmentId !== input.expectedEnvironmentId) {
-    return new CloudEnvironmentLinkError({
-      message: "Relay returned credentials for a different environment.",
+    return new CloudEnvironmentLinkResponseMismatchError({
+      environmentId: input.expectedEnvironmentId,
+      field: "environment id",
+      expected: input.expectedEnvironmentId,
+      actual: input.link.environmentId,
     });
   }
   if (input.link.endpoint.providerKind !== input.expectedProviderKind) {
-    return new CloudEnvironmentLinkError({
-      message: "Relay returned credentials for a different endpoint provider.",
+    return new CloudEnvironmentLinkResponseMismatchError({
+      environmentId: input.expectedEnvironmentId,
+      field: "endpoint provider",
+      expected: input.expectedProviderKind,
+      actual: input.link.endpoint.providerKind,
     });
   }
   return Effect.void;
@@ -275,9 +462,7 @@ export function listManagedCloudEnvironments(input: {
   return Effect.gen(function* () {
     const configuredRelayUrl = relayUrl();
     if (!configuredRelayUrl) {
-      return yield* new CloudEnvironmentLinkError({
-        message: "T3CODE_RELAY_URL is not configured.",
-      });
+      return yield* new CloudRelayUrlNotConfiguredError({});
     }
     const relayClient = yield* ManagedRelay.ManagedRelayClient;
     return yield* relayClient
@@ -285,12 +470,12 @@ export function listManagedCloudEnvironments(input: {
         clerkToken: input.clerkToken,
       })
       .pipe(
-        Effect.mapError(
-          (cause) =>
-            new CloudEnvironmentLinkError({
-              message: "Could not list relay-managed environments.",
-              cause,
-            }),
+        Effect.mapError((cause) =>
+          CloudEnvironmentLinkOperationError.fromManagedRelay({
+            action: "list relay-managed environments",
+            relayUrl: configuredRelayUrl,
+            cause,
+          }),
         ),
       );
   });
@@ -304,19 +489,18 @@ export function listCloudDevices(input: {
   ManagedRelay.ManagedRelayClient
 > {
   return Effect.gen(function* () {
-    if (!relayUrl()) {
-      return yield* new CloudEnvironmentLinkError({
-        message: "T3CODE_RELAY_URL is not configured.",
-      });
+    const configuredRelayUrl = relayUrl();
+    if (!configuredRelayUrl) {
+      return yield* new CloudRelayUrlNotConfiguredError({});
     }
     const relayClient = yield* ManagedRelay.ManagedRelayClient;
     return yield* relayClient.listDevices({ clerkToken: input.clerkToken }).pipe(
-      Effect.mapError(
-        (cause) =>
-          new CloudEnvironmentLinkError({
-            message: "Could not list cloud devices.",
-            cause,
-          }),
+      Effect.mapError((cause) =>
+        CloudEnvironmentLinkOperationError.fromManagedRelay({
+          action: "list cloud devices",
+          relayUrl: configuredRelayUrl,
+          cause,
+        }),
       ),
     );
   });
@@ -326,10 +510,20 @@ export function readPrimaryCloudLinkState(input: {
   readonly target: CloudLinkTarget;
 }): Effect.Effect<CloudLinkState | null, CloudEnvironmentLinkError, HttpClient.HttpClient> {
   return Effect.gen(function* () {
-    const client = yield* makeEnvironmentHttpApiClient(input.target.httpBaseUrl);
-    return yield* client.connect
-      .linkState({ headers: {} })
-      .pipe(Effect.mapError(environmentApiError("Could not read environment cloud link state.")));
+    const client = yield* makeCloudEnvironmentHttpApiClient({
+      environmentId: input.target.environmentId,
+      httpBaseUrl: input.target.httpBaseUrl,
+    });
+    return yield* client.connect.linkState({ headers: {} }).pipe(
+      Effect.mapError((cause) =>
+        CloudEnvironmentLinkOperationError.fromEnvironmentApi({
+          action: "read environment cloud link state",
+          environmentId: input.target.environmentId,
+          httpBaseUrl: input.target.httpBaseUrl,
+          cause,
+        }),
+      ),
+    );
   }).pipe(Effect.provide(primaryEnvironmentHttpLayer));
 }
 
@@ -338,14 +532,24 @@ export function updatePrimaryCloudPreferences(input: {
   readonly publishAgentActivity: boolean;
 }): Effect.Effect<CloudLinkState, CloudEnvironmentLinkError, HttpClient.HttpClient> {
   return Effect.gen(function* () {
-    const client = yield* makeEnvironmentHttpApiClient(input.target.httpBaseUrl);
+    const client = yield* makeCloudEnvironmentHttpApiClient({
+      environmentId: input.target.environmentId,
+      httpBaseUrl: input.target.httpBaseUrl,
+    });
     return yield* client.connect
       .preferences({
         headers: {},
         payload: input,
       })
       .pipe(
-        Effect.mapError(environmentApiError("Could not update environment cloud preferences.")),
+        Effect.mapError((cause) =>
+          CloudEnvironmentLinkOperationError.fromEnvironmentApi({
+            action: "update environment cloud preferences",
+            environmentId: input.target.environmentId,
+            httpBaseUrl: input.target.httpBaseUrl,
+            cause,
+          }),
+        ),
       );
   }).pipe(Effect.provide(primaryEnvironmentHttpLayer));
 }
@@ -359,10 +563,20 @@ export function unlinkPrimaryEnvironmentFromCloud(input: {
   HttpClient.HttpClient | ManagedRelay.ManagedRelayClient
 > {
   return Effect.gen(function* () {
-    const client = yield* makeEnvironmentHttpApiClient(input.target.httpBaseUrl);
-    yield* client.connect
-      .unlink({ headers: {} })
-      .pipe(Effect.mapError(environmentApiError("Could not unlink the environment from cloud.")));
+    const client = yield* makeCloudEnvironmentHttpApiClient({
+      environmentId: input.target.environmentId,
+      httpBaseUrl: input.target.httpBaseUrl,
+    });
+    yield* client.connect.unlink({ headers: {} }).pipe(
+      Effect.mapError((cause) =>
+        CloudEnvironmentLinkOperationError.fromEnvironmentApi({
+          action: "unlink the environment from cloud",
+          environmentId: input.target.environmentId,
+          httpBaseUrl: input.target.httpBaseUrl,
+          cause,
+        }),
+      ),
+    );
 
     const configuredRelayUrl = relayUrl();
     if (configuredRelayUrl && input.clerkToken) {
@@ -373,11 +587,27 @@ export function unlinkPrimaryEnvironmentFromCloud(input: {
           environmentId: EnvironmentId.make(input.target.environmentId),
         })
         .pipe(
-          Effect.catch((cause) =>
-            Effect.logWarning("Could not revoke cloud environment link after local unlink.", {
+          Effect.catch((cause) => {
+            const error = CloudEnvironmentLinkOperationError.fromManagedRelay({
+              action: "revoke the cloud environment link",
+              environmentId: input.target.environmentId,
+              relayUrl: configuredRelayUrl,
               cause,
-            }),
-          ),
+            });
+            return Effect.logWarning(error.message, {
+              environmentId: input.target.environmentId,
+              ...(error.relayUrlInputLength === undefined
+                ? {}
+                : { relayUrlInputLength: error.relayUrlInputLength }),
+              ...(error.relayUrlProtocol === undefined
+                ? {}
+                : { relayUrlProtocol: error.relayUrlProtocol }),
+              ...(error.relayUrlHostname === undefined
+                ? {}
+                : { relayUrlHostname: error.relayUrlHostname }),
+              causeTag: cause._tag,
+            });
+          }),
         );
     }
   }).pipe(Effect.provide(primaryEnvironmentHttpLayer));
@@ -394,12 +624,19 @@ export function linkPrimaryEnvironmentToCloud(input: {
   return Effect.gen(function* () {
     const configuredRelayUrl = relayUrl();
     if (!configuredRelayUrl) {
-      return yield* new CloudEnvironmentLinkError({
-        message: "T3CODE_RELAY_URL is not configured.",
+      return yield* new CloudRelayUrlNotConfiguredError({
+        environmentId: input.target.environmentId,
       });
     }
+    const origin = yield* endpointOrigin({
+      environmentId: input.target.environmentId,
+      httpBaseUrl: input.target.httpBaseUrl,
+    });
+    const environmentClient = yield* makeCloudEnvironmentHttpApiClient({
+      environmentId: input.target.environmentId,
+      httpBaseUrl: input.target.httpBaseUrl,
+    });
     const relayClient = yield* ManagedRelay.ManagedRelayClient;
-    const environmentClient = yield* makeEnvironmentHttpApiClient(input.target.httpBaseUrl);
     yield* ensureRelayClientAvailable(EnvironmentId.make(input.target.environmentId));
 
     const challenge = yield* relayClient
@@ -412,10 +649,13 @@ export function linkPrimaryEnvironmentToCloud(input: {
         },
       })
       .pipe(
-        Effect.mapError(
-          decodedRelayClientError(
-            `${configuredRelayUrl}/v1/client/environment-link-challenges failed`,
-          ),
+        Effect.mapError((cause) =>
+          CloudEnvironmentLinkOperationError.fromManagedRelay({
+            action: "create an environment link challenge",
+            environmentId: input.target.environmentId,
+            relayUrl: configuredRelayUrl,
+            cause,
+          }),
         ),
       );
     const proof = yield* environmentClient.connect
@@ -429,10 +669,19 @@ export function linkPrimaryEnvironmentToCloud(input: {
             wsBaseUrl: input.target.wsBaseUrl,
             providerKind: MANAGED_ENDPOINT_PROVIDER_KIND,
           },
-          origin: endpointOrigin(input.target.httpBaseUrl),
+          origin,
         },
       })
-      .pipe(Effect.mapError(environmentApiError("Could not obtain environment link proof.")));
+      .pipe(
+        Effect.mapError((cause) =>
+          CloudEnvironmentLinkOperationError.fromEnvironmentApi({
+            action: "obtain an environment link proof",
+            environmentId: input.target.environmentId,
+            httpBaseUrl: input.target.httpBaseUrl,
+            cause,
+          }),
+        ),
+      );
     const link = yield* relayClient
       .linkEnvironment({
         clerkToken: input.clerkToken,
@@ -444,8 +693,13 @@ export function linkPrimaryEnvironmentToCloud(input: {
         },
       })
       .pipe(
-        Effect.mapError(
-          decodedRelayClientError(`${configuredRelayUrl}/v1/client/environment-links failed`),
+        Effect.mapError((cause) =>
+          CloudEnvironmentLinkOperationError.fromManagedRelay({
+            action: "link the environment",
+            environmentId: input.target.environmentId,
+            relayUrl: configuredRelayUrl,
+            cause,
+          }),
         ),
       );
     yield* ensureLinkedEnvironmentMatches({
@@ -466,6 +720,15 @@ export function linkPrimaryEnvironmentToCloud(input: {
           endpointRuntime: link.endpointRuntime,
         },
       })
-      .pipe(Effect.mapError(environmentApiError("Could not configure environment relay access.")));
+      .pipe(
+        Effect.mapError((cause) =>
+          CloudEnvironmentLinkOperationError.fromEnvironmentApi({
+            action: "configure environment relay access",
+            environmentId: input.target.environmentId,
+            httpBaseUrl: input.target.httpBaseUrl,
+            cause,
+          }),
+        ),
+      );
   }).pipe(Effect.provide(primaryEnvironmentHttpLayer));
 }
diff --git a/apps/web/src/cloud/managedRelayLayer.ts b/apps/web/src/cloud/managedRelayLayer.ts
index 52f9b6496c9..6fc631f40ff 100644
--- a/apps/web/src/cloud/managedRelayLayer.ts
+++ b/apps/web/src/cloud/managedRelayLayer.ts
@@ -50,25 +50,24 @@ export const relayDpopSignerLayer = Layer.effect(
       ),
       createProof: Effect.fn("web.managedRelayDpopSigner.createProof")(function* (input) {
         const proofKey = yield* loadOrCreateBrowserDpopKey.pipe(
-          Effect.mapError(
-            (error) =>
-              new ManagedRelay.ManagedRelayDpopProofCreationError({
-                method: input.method,
-                url: input.url,
-                cause: error,
-              }),
+          Effect.mapError((error) =>
+            ManagedRelay.ManagedRelayDpopKeyLoadError.fromTarget({
+              keyStore: "indexed-db",
+              method: input.method,
+              url: input.url,
+              cause: error,
+            }),
           ),
         );
         return yield* createBrowserDpopProof({ ...input, proofKey }).pipe(
           Effect.provideService(Crypto.Crypto, crypto),
           Effect.map((proof) => proof.proof),
-          Effect.mapError(
-            (error) =>
-              new ManagedRelay.ManagedRelayDpopProofCreationError({
-                method: input.method,
-                url: input.url,
-                cause: error,
-              }),
+          Effect.mapError((error) =>
+            ManagedRelay.ManagedRelayDpopProofCreationError.fromTarget({
+              method: input.method,
+              url: input.url,
+              cause: error,
+            }),
           ),
         );
       }),
diff --git a/apps/web/src/components/preview/PreviewMoreMenu.tsx b/apps/web/src/components/preview/PreviewMoreMenu.tsx
index f11ff4d2d30..6ffefe53600 100644
--- a/apps/web/src/components/preview/PreviewMoreMenu.tsx
+++ b/apps/web/src/components/preview/PreviewMoreMenu.tsx
@@ -7,6 +7,7 @@ import { Menu, MenuItem, MenuPopup, MenuSeparator, MenuTrigger } from "~/compone
 import { Tooltip, TooltipPopup, TooltipTrigger } from "~/components/ui/tooltip";
 
 import { previewBridge } from "./previewBridge";
+import { reportPreviewActionFailure } from "./reportPreviewActionFailure";
 
 interface Props {
   /** Active preview tab id. Tab-targeting actions are disabled without it. */
@@ -30,9 +31,11 @@ export function PreviewMoreMenu({ tabId, hasWebContents, zoomFactor }: Props) {
   if (!previewBridge) return null;
   const bridge = previewBridge;
   const tabDisabled = !tabId || !hasWebContents;
-  const callTab = (op: (tabId: string) => Promise<void>) => () => {
+  const callTab = (operation: string, op: (tabId: string) => Promise<void>) => () => {
     if (!tabId) return;
-    void op(tabId).catch(() => undefined);
+    void op(tabId).catch((cause) => {
+      reportPreviewActionFailure({ operation, tabId }, cause);
+    });
   };
 
   const zoomLabel = `${Math.round(zoomFactor * 100)}%`;
@@ -53,10 +56,10 @@ export function PreviewMoreMenu({ tabId, hasWebContents, zoomFactor }: Props) {
         <TooltipPopup>More</TooltipPopup>
       </Tooltip>
       <MenuPopup align="end" sideOffset={6} className="min-w-56">
-        <MenuItem onClick={callTab(bridge.hardReload)} disabled={tabDisabled}>
+        <MenuItem onClick={callTab("hard-reload", bridge.hardReload)} disabled={tabDisabled}>
           Hard reload
         </MenuItem>
-        <MenuItem onClick={callTab(bridge.openDevTools)} disabled={tabDisabled}>
+        <MenuItem onClick={callTab("open-devtools", bridge.openDevTools)} disabled={tabDisabled}>
           Open DevTools
         </MenuItem>
         {/*
@@ -75,7 +78,7 @@ export function PreviewMoreMenu({ tabId, hasWebContents, zoomFactor }: Props) {
               variant="outline"
               size="icon-xs"
               type="button"
-              onClick={callTab(bridge.zoomOut)}
+              onClick={callTab("zoom-out", bridge.zoomOut)}
               aria-label="Zoom out"
               disabled={tabDisabled}
             >
@@ -88,7 +91,7 @@ export function PreviewMoreMenu({ tabId, hasWebContents, zoomFactor }: Props) {
               variant="outline"
               size="icon-xs"
               type="button"
-              onClick={callTab(bridge.zoomIn)}
+              onClick={callTab("zoom-in", bridge.zoomIn)}
               aria-label="Zoom in"
               disabled={tabDisabled}
             >
@@ -98,7 +101,7 @@ export function PreviewMoreMenu({ tabId, hasWebContents, zoomFactor }: Props) {
               variant="ghost"
               size="icon-xs"
               type="button"
-              onClick={callTab(bridge.resetZoom)}
+              onClick={callTab("reset-zoom", bridge.resetZoom)}
               aria-label="Reset zoom"
               disabled={tabDisabled}
             >
@@ -107,10 +110,22 @@ export function PreviewMoreMenu({ tabId, hasWebContents, zoomFactor }: Props) {
           </span>
         </MenuItem>
         <MenuSeparator />
-        <MenuItem onClick={() => void bridge.clearCookies().catch(() => undefined)}>
+        <MenuItem
+          onClick={() =>
+            void bridge.clearCookies().catch((cause) => {
+              reportPreviewActionFailure({ operation: "clear-cookies" }, cause);
+            })
+          }
+        >
           Clear cookies
         </MenuItem>
-        <MenuItem onClick={() => void bridge.clearCache().catch(() => undefined)}>
+        <MenuItem
+          onClick={() =>
+            void bridge.clearCache().catch((cause) => {
+              reportPreviewActionFailure({ operation: "clear-cache" }, cause);
+            })
+          }
+        >
           Clear cache
         </MenuItem>
       </MenuPopup>
diff --git a/apps/web/src/components/preview/PreviewView.tsx b/apps/web/src/components/preview/PreviewView.tsx
index 861a8df616b..038859f881a 100644
--- a/apps/web/src/components/preview/PreviewView.tsx
+++ b/apps/web/src/components/preview/PreviewView.tsx
@@ -1,6 +1,7 @@
 "use client";
 
 import { scopedThreadKey } from "@t3tools/client-runtime/environment";
+import { isAtomCommandInterrupted } from "@t3tools/client-runtime/state/runtime";
 import { type ScopedThreadRef } from "@t3tools/contracts";
 import { useCallback, useEffect, useRef, useState } from "react";
 
@@ -20,6 +21,7 @@ import { PreviewChromeRow } from "./PreviewChromeRow";
 import { formatPreviewUrl } from "./previewUrlPresentation";
 import { PreviewEmptyState } from "./PreviewEmptyState";
 import { PreviewMoreMenu } from "./PreviewMoreMenu";
+import { previewUrlFailureContext, reportPreviewActionFailure } from "./reportPreviewActionFailure";
 import { PreviewUnreachable } from "./PreviewUnreachable";
 import { revealInFileExplorerLabel } from "./fileExplorerLabel";
 import { shouldShowPreviewEmptyState } from "./previewEmptyStateLogic";
@@ -91,58 +93,112 @@ export function PreviewView({ threadRef, tabId: requestedTabId, configuredUrls,
           environmentHttpBaseUrl,
         }) ?? undefined)
       : undefined;
+  const threadKey = scopedThreadKey(threadRef);
 
   const handleSubmitUrl = useCallback(
     async (next: string) => {
+      let operation = "resolve-url";
+      let targetUrl = next;
       try {
         const resolvedUrl = resolveDiscoveredServerUrl(threadRef.environmentId, next);
+        targetUrl = resolvedUrl;
         if (tabId && previewBridge) {
           // Drive the webview imperatively; `usePreviewBridge` mirrors the
           // resolved URL back to the server so other clients stay in sync.
+          operation = "navigate";
           await previewBridge.navigate(tabId, resolvedUrl);
           rememberPreviewUrl(threadRef, resolvedUrl);
         } else {
-          await openPreviewSession({
+          operation = "open-session";
+          const result = await openPreviewSession({
             openPreview: open,
             threadRef,
             url: resolvedUrl,
           });
+          if (result._tag === "Failure" && !isAtomCommandInterrupted(result)) {
+            reportPreviewActionFailure(
+              {
+                operation,
+                threadKey,
+                ...(tabId ? { tabId } : {}),
+                ...previewUrlFailureContext(targetUrl),
+              },
+              result.cause,
+            );
+          }
         }
-      } catch {
+      } catch (cause) {
+        reportPreviewActionFailure(
+          {
+            operation,
+            threadKey,
+            ...(tabId ? { tabId } : {}),
+            ...previewUrlFailureContext(targetUrl),
+          },
+          cause,
+        );
         // Server-side `failed` event renders the unreachable view.
       }
     },
-    [open, tabId, threadRef],
+    [open, tabId, threadKey, threadRef],
   );
 
   const handleRefresh = useCallback(() => {
-    if (previewBridge && tabId) void previewBridge.refresh(tabId);
-  }, [tabId]);
+    if (!previewBridge || !tabId) return;
+    void previewBridge.refresh(tabId).catch((cause) => {
+      reportPreviewActionFailure({ operation: "refresh", threadKey, tabId }, cause);
+    });
+  }, [tabId, threadKey]);
 
   const handleZoomIn = useCallback(() => {
-    if (previewBridge && tabId) void previewBridge.zoomIn(tabId);
-  }, [tabId]);
+    if (!previewBridge || !tabId) return;
+    void previewBridge.zoomIn(tabId).catch((cause) => {
+      reportPreviewActionFailure({ operation: "zoom-in", threadKey, tabId }, cause);
+    });
+  }, [tabId, threadKey]);
 
   const handleZoomOut = useCallback(() => {
-    if (previewBridge && tabId) void previewBridge.zoomOut(tabId);
-  }, [tabId]);
+    if (!previewBridge || !tabId) return;
+    void previewBridge.zoomOut(tabId).catch((cause) => {
+      reportPreviewActionFailure({ operation: "zoom-out", threadKey, tabId }, cause);
+    });
+  }, [tabId, threadKey]);
 
   const handleResetZoom = useCallback(() => {
-    if (previewBridge && tabId) void previewBridge.resetZoom(tabId);
-  }, [tabId]);
+    if (!previewBridge || !tabId) return;
+    void previewBridge.resetZoom(tabId).catch((cause) => {
+      reportPreviewActionFailure({ operation: "reset-zoom", threadKey, tabId }, cause);
+    });
+  }, [tabId, threadKey]);
 
   const handleBack = useCallback(() => {
-    if (previewBridge && tabId) void previewBridge.goBack(tabId);
-  }, [tabId]);
+    if (!previewBridge || !tabId) return;
+    void previewBridge.goBack(tabId).catch((cause) => {
+      reportPreviewActionFailure({ operation: "go-back", threadKey, tabId }, cause);
+    });
+  }, [tabId, threadKey]);
 
   const handleForward = useCallback(() => {
-    if (previewBridge && tabId) void previewBridge.goForward(tabId);
-  }, [tabId]);
+    if (!previewBridge || !tabId) return;
+    void previewBridge.goForward(tabId).catch((cause) => {
+      reportPreviewActionFailure({ operation: "go-forward", threadKey, tabId }, cause);
+    });
+  }, [tabId, threadKey]);
 
   const handleOpenInBrowser = useCallback(() => {
     if (!localApi || !url) return;
-    void localApi.shell.openExternal(url).catch(() => undefined);
-  }, [url]);
+    void localApi.shell.openExternal(url).catch((cause) => {
+      reportPreviewActionFailure(
+        {
+          operation: "open-external",
+          threadKey,
+          ...(tabId ? { tabId } : {}),
+          ...previewUrlFailureContext(url),
+        },
+        cause,
+      );
+    });
+  }, [tabId, threadKey, url]);
 
   const handleCapture = useCallback(
     (record: boolean) => {
@@ -180,6 +236,15 @@ export function PreviewView({ threadRef, tabId: requestedTabId, configuredUrls,
                   }, 2_000);
                 },
                 (error) => {
+                  reportPreviewActionFailure(
+                    {
+                      operation: "copy-recording-path",
+                      threadKey,
+                      tabId,
+                      artifactPath: artifact.path,
+                    },
+                    error,
+                  );
                   toastManager.update(
                     toastId,
                     stackedThreadToast({
@@ -195,7 +260,18 @@ export function PreviewView({ threadRef, tabId: requestedTabId, configuredUrls,
 
             const revealAction = {
               children: revealInFileExplorerLabel(navigator.platform),
-              onClick: () => void bridge.revealArtifact(artifact.path),
+              onClick: () =>
+                void bridge.revealArtifact(artifact.path).catch((cause) => {
+                  reportPreviewActionFailure(
+                    {
+                      operation: "reveal-recording",
+                      threadKey,
+                      tabId,
+                      artifactPath: artifact.path,
+                    },
+                    cause,
+                  );
+                }),
             };
             const updateRecordingToast = () => {
               toastManager.update(
@@ -232,6 +308,7 @@ export function PreviewView({ threadRef, tabId: requestedTabId, configuredUrls,
             );
           },
           (error) => {
+            reportPreviewActionFailure({ operation: "stop-recording", threadKey, tabId }, error);
             toastManager.add({
               type: "error",
               title: "Unable to stop recording",
@@ -251,6 +328,7 @@ export function PreviewView({ threadRef, tabId: requestedTabId, configuredUrls,
           return;
         }
         void startBrowserRecording(tabId).catch((error) => {
+          reportPreviewActionFailure({ operation: "start-recording", threadKey, tabId }, error);
           toastManager.add({
             type: "error",
             title: "Unable to start recording",
@@ -263,7 +341,18 @@ export function PreviewView({ threadRef, tabId: requestedTabId, configuredUrls,
         (artifact) => {
           const revealAction = {
             children: revealInFileExplorerLabel(navigator.platform),
-            onClick: () => void bridge.revealArtifact(artifact.path),
+            onClick: () =>
+              void bridge.revealArtifact(artifact.path).catch((cause) => {
+                reportPreviewActionFailure(
+                  {
+                    operation: "reveal-screenshot",
+                    threadKey,
+                    tabId,
+                    artifactPath: artifact.path,
+                  },
+                  cause,
+                );
+              }),
           };
           let pathCopied = false;
           let imageCopied = false;
@@ -325,6 +414,15 @@ export function PreviewView({ threadRef, tabId: requestedTabId, configuredUrls,
                 }, 2_000);
               },
               (error) => {
+                reportPreviewActionFailure(
+                  {
+                    operation: "copy-screenshot-path",
+                    threadKey,
+                    tabId,
+                    artifactPath: artifact.path,
+                  },
+                  error,
+                );
                 updateScreenshotToast(
                   "error",
                   "Unable to copy screenshot path",
@@ -345,6 +443,15 @@ export function PreviewView({ threadRef, tabId: requestedTabId, configuredUrls,
                 }, 2_000);
               },
               (error) => {
+                reportPreviewActionFailure(
+                  {
+                    operation: "copy-screenshot-image",
+                    threadKey,
+                    tabId,
+                    artifactPath: artifact.path,
+                  },
+                  error,
+                );
                 updateScreenshotToast(
                   "error",
                   "Unable to copy screenshot",
@@ -381,6 +488,7 @@ export function PreviewView({ threadRef, tabId: requestedTabId, configuredUrls,
           );
         },
         (error) => {
+          reportPreviewActionFailure({ operation: "capture-screenshot", threadKey, tabId }, error);
           toastManager.add({
             type: "error",
             title: "Unable to capture screenshot",
@@ -389,13 +497,18 @@ export function PreviewView({ threadRef, tabId: requestedTabId, configuredUrls,
         },
       );
     },
-    [activeRecordingTabId, tabId],
+    [activeRecordingTabId, tabId, threadKey],
   );
 
   const handlePickElement = useCallback(() => {
     if (!previewBridge || !tabId) return;
     if (pickActiveRef.current) {
-      void previewBridge.cancelPickElement(tabId).catch(() => undefined);
+      void previewBridge.cancelPickElement(tabId).catch((cause) => {
+        reportPreviewActionFailure(
+          { operation: "cancel-element-picker", threadKey, tabId, trigger: "toggle" },
+          cause,
+        );
+      });
       return;
     }
     // Snapshot whatever the user was focused on (typically the chat
@@ -408,12 +521,18 @@ export function PreviewView({ threadRef, tabId: requestedTabId, configuredUrls,
     pickActiveRef.current = true;
     setPickActive(true);
     void (async () => {
+      let operation = "pick-element";
+      let annotationId: string | undefined;
       try {
         const annotation = await previewBridge.pickElement(tabId);
         if (!annotation) return;
+        annotationId = annotation.id;
+        operation = "add-preview-annotation";
         addPreviewAnnotation(threadRef, annotation);
+        operation = "prepare-annotation-screenshot";
         const screenshotFile = await previewAnnotationScreenshotFile(annotation);
         if (screenshotFile && annotation.screenshot) {
+          operation = "attach-annotation-screenshot";
           addImage(threadRef, {
             type: "image",
             id: annotation.id,
@@ -424,8 +543,17 @@ export function PreviewView({ threadRef, tabId: requestedTabId, configuredUrls,
             file: screenshotFile,
           });
         }
-      } catch {
-        // Picker failed (e.g. webview navigated). Treat as silent cancel.
+      } catch (cause) {
+        reportPreviewActionFailure(
+          {
+            operation,
+            threadKey,
+            tabId,
+            ...(annotationId ? { annotationId } : {}),
+          },
+          cause,
+        );
+        // Keep picker failures silent in the UI; navigating during a pick is expected.
       } finally {
         pickActiveRef.current = false;
         // Avoid `setState on unmounted component` if the panel/thread closed
@@ -447,7 +575,7 @@ export function PreviewView({ threadRef, tabId: requestedTabId, configuredUrls,
         }
       }
     })();
-  }, [addImage, addPreviewAnnotation, tabId, threadRef]);
+  }, [addImage, addPreviewAnnotation, tabId, threadKey, threadRef]);
 
   // If the active tab changes mid-pick (close, thread switch, hot restart),
   // tell main to tear down the in-flight session AND reset our local toggle
@@ -457,11 +585,16 @@ export function PreviewView({ threadRef, tabId: requestedTabId, configuredUrls,
       if (!pickActiveRef.current) return;
       pickActiveRef.current = false;
       if (previewBridge && tabId) {
-        void previewBridge.cancelPickElement(tabId).catch(() => undefined);
+        void previewBridge.cancelPickElement(tabId).catch((cause) => {
+          reportPreviewActionFailure(
+            { operation: "cancel-element-picker", threadKey, tabId, trigger: "tab-change" },
+            cause,
+          );
+        });
       }
       if (isMountedRef.current) setPickActive(false);
     };
-  }, [tabId]);
+  }, [tabId, threadKey]);
 
   // Subscribe only while visible; `toggle-panel` is owned by ChatView's
   // URL-aware handler regardless of whether the panel is currently mounted.
@@ -491,10 +624,7 @@ export function PreviewView({ threadRef, tabId: requestedTabId, configuredUrls,
   }, [handleRefresh, handleResetZoom, handleZoomIn, handleZoomOut, visible]);
 
   return (
-    <div
-      className="flex min-h-0 flex-1 flex-col bg-background"
-      data-thread-key={scopedThreadKey(threadRef)}
-    >
+    <div className="flex min-h-0 flex-1 flex-col bg-background" data-thread-key={threadKey}>
       <PreviewChromeRow
         url={url}
         displayUrl={displayUrl}
diff --git a/apps/web/src/components/preview/reportPreviewActionFailure.test.ts b/apps/web/src/components/preview/reportPreviewActionFailure.test.ts
new file mode 100644
index 00000000000..9ae9648d1dc
--- /dev/null
+++ b/apps/web/src/components/preview/reportPreviewActionFailure.test.ts
@@ -0,0 +1,37 @@
+import { describe, expect, it, vi } from "vite-plus/test";
+
+import { previewUrlFailureContext, reportPreviewActionFailure } from "./reportPreviewActionFailure";
+
+describe("reportPreviewActionFailure", () => {
+  it("logs safe preview target metadata without credentials or URL parameters", () => {
+    const url =
+      "https://user:password@example.com/preview/signed-secret-token?access_token=private#fragment";
+    const cause = new Error("navigation failed");
+    const consoleError = vi.spyOn(console, "error").mockImplementation(() => undefined);
+
+    reportPreviewActionFailure(
+      {
+        operation: "navigate",
+        ...previewUrlFailureContext(url),
+      },
+      cause,
+    );
+
+    expect(consoleError).toHaveBeenCalledWith(
+      "[preview] action failed",
+      {
+        operation: "navigate",
+        urlHostname: "example.com",
+        urlLength: url.length,
+        urlProtocol: "https:",
+      },
+      cause,
+    );
+    const loggedContext = consoleError.mock.calls[0]?.[1];
+    expect(loggedContext).not.toHaveProperty("url");
+    expect(JSON.stringify(loggedContext)).not.toContain("signed-secret-token");
+    expect(JSON.stringify(loggedContext)).not.toContain("access_token=private");
+
+    consoleError.mockRestore();
+  });
+});
diff --git a/apps/web/src/components/preview/reportPreviewActionFailure.ts b/apps/web/src/components/preview/reportPreviewActionFailure.ts
new file mode 100644
index 00000000000..ceaac4cd1a9
--- /dev/null
+++ b/apps/web/src/components/preview/reportPreviewActionFailure.ts
@@ -0,0 +1,29 @@
+import { getUrlDiagnostics } from "@t3tools/shared/urlDiagnostics";
+
+export interface PreviewActionFailureContext {
+  readonly operation: string;
+  readonly threadKey?: string;
+  readonly tabId?: string;
+  readonly urlHostname?: string;
+  readonly urlLength?: number;
+  readonly urlProtocol?: string;
+  readonly artifactPath?: string;
+  readonly annotationId?: string;
+  readonly trigger?: string;
+}
+
+export function previewUrlFailureContext(url: string) {
+  const diagnostics = getUrlDiagnostics(url);
+  return {
+    urlLength: diagnostics.inputLength,
+    ...(diagnostics.hostname === undefined ? {} : { urlHostname: diagnostics.hostname }),
+    ...(diagnostics.protocol === undefined ? {} : { urlProtocol: diagnostics.protocol }),
+  };
+}
+
+export function reportPreviewActionFailure(
+  context: PreviewActionFailureContext,
+  cause: unknown,
+): void {
+  console.error("[preview] action failed", context, cause);
+}
diff --git a/apps/web/src/components/settings/ConnectionsSettings.tsx b/apps/web/src/components/settings/ConnectionsSettings.tsx
index 96d9dd4510f..a8bb5f20f01 100644
--- a/apps/web/src/components/settings/ConnectionsSettings.tsx
+++ b/apps/web/src/components/settings/ConnectionsSettings.tsx
@@ -1837,7 +1837,7 @@ function ConfiguredCloudRemoteEnvironmentRows({
                     ? "Relay offline"
                     : availability === "checking"
                       ? "Checking relay status"
-                      : (Option.getOrNull(error)?.message ?? "Relay status unavailable")
+                      : (Option.getOrNull(error)?.detail ?? "Relay status unavailable")
               }
             />
             <p className="truncate text-sm font-medium">{environment.label}</p>
@@ -1854,7 +1854,7 @@ function ConfiguredCloudRemoteEnvironmentRows({
                 ? "Available · Relay offline"
                 : availability === "checking"
                   ? "Available · Checking relay status…"
-                  : (Option.getOrNull(error)?.message ?? "Available · Relay status unavailable")}
+                  : (Option.getOrNull(error)?.detail ?? "Available · Relay status unavailable")}
           </p>
         </div>
         <Button
diff --git a/apps/web/src/connection/platform.test.ts b/apps/web/src/connection/platform.test.ts
index 2b428e26698..1f26e0f0009 100644
--- a/apps/web/src/connection/platform.test.ts
+++ b/apps/web/src/connection/platform.test.ts
@@ -1,5 +1,10 @@
+import {
+  ConnectionBlockedError,
+  ConnectionTransientError,
+} from "@t3tools/client-runtime/connection";
 import {
   AuthStandardClientScopes,
+  DesktopSshPasswordPromptCancellationError,
   EnvironmentId,
   type DesktopBridge,
   type DesktopSshEnvironmentTarget,
@@ -18,11 +23,14 @@ const TARGET: DesktopSshEnvironmentTarget = {
 
 function makeBridge(
   calls: string[],
-  options?: { readonly failDescriptor?: boolean },
+  options?: { readonly descriptorError?: unknown; readonly ensureError?: unknown },
 ): DesktopBridge {
   return {
     ensureSshEnvironment: async (target: DesktopSshEnvironmentTarget) => {
       calls.push("ensure");
+      if (options?.ensureError !== undefined) {
+        throw options.ensureError;
+      }
       return {
         target,
         httpBaseUrl: "http://127.0.0.1:3201/",
@@ -32,8 +40,8 @@ function makeBridge(
     },
     fetchSshEnvironmentDescriptor: async () => {
       calls.push("descriptor");
-      if (options?.failDescriptor === true) {
-        throw new Error("descriptor unavailable");
+      if (options?.descriptorError !== undefined) {
+        throw options.descriptorError;
       }
       return {
         environmentId: EnvironmentId.make("environment-ssh"),
@@ -78,11 +86,67 @@ describe("desktop SSH pairing", () => {
       const calls: string[] = [];
 
       yield* provisionDesktopSshEnvironment(
-        makeBridge(calls, { failDescriptor: true }),
+        makeBridge(calls, { descriptorError: new Error("descriptor unavailable") }),
         TARGET,
       ).pipe(Effect.flip);
 
       expect(calls).toEqual(["ensure", "descriptor"]);
     }),
   );
+
+  it.effect("preserves SSH preparation causes without exposing their message", () =>
+    Effect.gen(function* () {
+      const cause = new Error("descriptor response contained a private endpoint");
+
+      const error = yield* provisionDesktopSshEnvironment(
+        makeBridge([], { descriptorError: cause }),
+        TARGET,
+      ).pipe(Effect.flip);
+
+      expect(error).toBeInstanceOf(ConnectionTransientError);
+      expect(error.detail).toBe("Could not prepare the SSH environment.");
+      expect(error.message).toBe("Connection attempt failed (remote-unavailable).");
+      expect(error.message).not.toContain(cause.message);
+      expect(error.cause).toBe(cause);
+    }),
+  );
+
+  it.effect("classifies password prompt cancellation from its tag and preserves its cause", () =>
+    Effect.gen(function* () {
+      const promptCause = new Error("password prompt closed");
+      const cancellation = new DesktopSshPasswordPromptCancellationError({
+        reason: "window-closed",
+        requestId: "prompt-1",
+        destination: "developer@devbox.example.test",
+        cause: promptCause,
+      });
+
+      const error = yield* provisionDesktopSshEnvironment(
+        makeBridge([], { ensureError: cancellation }),
+        TARGET,
+      ).pipe(Effect.flip);
+
+      expect(error).toBeInstanceOf(ConnectionBlockedError);
+      expect(error.detail).toBe(
+        "SSH authentication did not complete for developer@devbox.example.test.",
+      );
+      expect(error.message).toBe("Connection attempt blocked (authentication).");
+      expect(error.cause).toBe(cancellation);
+      expect(cancellation.cause).toBe(promptCause);
+    }),
+  );
+
+  it.effect("does not infer cancellation from an unstructured error message", () =>
+    Effect.gen(function* () {
+      const cause = new Error("remote operation was cancelled");
+
+      const error = yield* provisionDesktopSshEnvironment(
+        makeBridge([], { ensureError: cause }),
+        TARGET,
+      ).pipe(Effect.flip);
+
+      expect(error).toBeInstanceOf(ConnectionTransientError);
+      expect(error.cause).toBe(cause);
+    }),
+  );
 });
diff --git a/apps/web/src/connection/platform.ts b/apps/web/src/connection/platform.ts
index 1b7cba5cbfd..b908762f37f 100644
--- a/apps/web/src/connection/platform.ts
+++ b/apps/web/src/connection/platform.ts
@@ -21,6 +21,7 @@ import { managedRelayAccountChanges, managedRelaySessionAtom } from "@t3tools/cl
 import { EnvironmentRpcRequestObserver } from "@t3tools/client-runtime/rpc";
 import {
   AuthStandardClientScopes,
+  isDesktopSshPasswordPromptCancellationError,
   type DesktopBridge,
   type DesktopSshEnvironmentTarget,
 } from "@t3tools/contracts";
@@ -105,30 +106,36 @@ function clientMetadata() {
   };
 }
 
-function sshPreparationError(cause: unknown) {
-  const message = cause instanceof Error ? cause.message : String(cause);
-  if (message.toLowerCase().includes("cancel")) {
-    return new ConnectionBlockedError({
-      reason: "authentication",
-      detail: message,
-    });
-  }
-  return new ConnectionTransientError({
-    reason: "remote-unavailable",
-    detail: `Could not prepare the SSH environment: ${message}`,
-  });
-}
+const trySshPreparation = <A>(operation: () => Promise<A>) =>
+  Effect.tryPromise({
+    try: operation,
+    catch: (cause) =>
+      isDesktopSshPasswordPromptCancellationError(cause)
+        ? cause
+        : new ConnectionTransientError({
+            reason: "remote-unavailable",
+            detail: "Could not prepare the SSH environment.",
+            cause,
+          }),
+  }).pipe(
+    Effect.catchTags({
+      DesktopSshPasswordPromptCancellationError: (cause) =>
+        new ConnectionBlockedError({
+          reason: "authentication",
+          detail: cause.message,
+          cause,
+        }),
+    }),
+  );
 
 export const provisionDesktopSshEnvironment = Effect.fn(
   "web.connectionPlatform.ssh.provisionDesktop",
 )(function* (bridge: DesktopBridge, target: DesktopSshEnvironmentTarget) {
-  const bootstrap = yield* Effect.tryPromise({
-    try: () =>
-      bridge.ensureSshEnvironment(target, {
-        issuePairingToken: true,
-      }),
-    catch: sshPreparationError,
-  });
+  const bootstrap = yield* trySshPreparation(() =>
+    bridge.ensureSshEnvironment(target, {
+      issuePairingToken: true,
+    }),
+  );
   const pairingToken = bootstrap.pairingToken;
   if (pairingToken === null) {
     return yield* new ConnectionBlockedError({
@@ -136,14 +143,12 @@ export const provisionDesktopSshEnvironment = Effect.fn(
       detail: "The SSH environment did not issue a pairing credential.",
     });
   }
-  const descriptor = yield* Effect.tryPromise({
-    try: () => bridge.fetchSshEnvironmentDescriptor(bootstrap.httpBaseUrl),
-    catch: sshPreparationError,
-  });
-  const access = yield* Effect.tryPromise({
-    try: () => bridge.bootstrapSshBearerSession(bootstrap.httpBaseUrl, pairingToken),
-    catch: sshPreparationError,
-  });
+  const descriptor = yield* trySshPreparation(() =>
+    bridge.fetchSshEnvironmentDescriptor(bootstrap.httpBaseUrl),
+  );
+  const access = yield* trySshPreparation(() =>
+    bridge.bootstrapSshBearerSession(bootstrap.httpBaseUrl, pairingToken),
+  );
   return {
     environmentId: descriptor.environmentId,
     label: descriptor.label,
@@ -172,7 +177,8 @@ const capabilitiesLayer = Layer.effectContext(
             (error) =>
               new ConnectionTransientError({
                 reason: "network",
-                detail: error.message,
+                detail: "Could not read the T3 Cloud session token.",
+                cause: error,
               }),
           ),
         );
@@ -194,7 +200,8 @@ const capabilitiesLayer = Layer.effectContext(
         catch: (cause) =>
           new ConnectionTransientError({
             reason: "remote-unavailable",
-            detail: `Could not load the desktop primary credential: ${String(cause)}`,
+            detail: "Could not load the desktop primary credential.",
+            cause,
           }),
       }).pipe(Effect.map(Option.fromNullishOr)),
     });
@@ -217,24 +224,20 @@ const capabilitiesLayer = Layer.effectContext(
             detail: "SSH environments are only available in the desktop app.",
           });
         }
-        const bootstrap = yield* Effect.tryPromise({
-          try: () =>
-            bridge.ensureSshEnvironment(input.target, {
-              issuePairingToken: true,
-            }),
-          catch: sshPreparationError,
-        });
+        const bootstrap = yield* trySshPreparation(() =>
+          bridge.ensureSshEnvironment(input.target, {
+            issuePairingToken: true,
+          }),
+        );
         if (bootstrap.pairingToken === null) {
           return yield* new ConnectionBlockedError({
             reason: "authentication",
             detail: "The SSH environment did not issue a pairing credential.",
           });
         }
-        const access = yield* Effect.tryPromise({
-          try: () =>
-            bridge.bootstrapSshBearerSession(bootstrap.httpBaseUrl, bootstrap.pairingToken!),
-          catch: sshPreparationError,
-        });
+        const access = yield* trySshPreparation(() =>
+          bridge.bootstrapSshBearerSession(bootstrap.httpBaseUrl, bootstrap.pairingToken!),
+        );
         return {
           bootstrap,
           bearerToken: access.access_token,
@@ -250,7 +253,8 @@ const capabilitiesLayer = Layer.effectContext(
           catch: (cause) =>
             new ConnectionTransientError({
               reason: "remote-unavailable",
-              detail: `Could not disconnect the SSH environment: ${String(cause)}`,
+              detail: "Could not disconnect the SSH environment.",
+              cause,
             }),
         });
       }),
diff --git a/apps/web/src/connection/storage.test.ts b/apps/web/src/connection/storage.test.ts
index 6d503387bb6..8427ca638c0 100644
--- a/apps/web/src/connection/storage.test.ts
+++ b/apps/web/src/connection/storage.test.ts
@@ -70,8 +70,34 @@ describe("makeCatalogBackend", () => {
       const error = yield* backend.write("{}").pipe(Effect.flip);
 
       expect(error).toBeInstanceOf(ConnectionTransientError);
-      expect(error.message).toContain("Desktop secure storage is unavailable");
+      expect(error.detail).toContain("Desktop secure storage is unavailable");
+      expect(error.message).toBe("Connection attempt failed (remote-unavailable).");
+      expect(error.cause).toMatchObject({ _tag: "DesktopSecureStorageUnavailableError" });
       expect(setConnectionCatalog).toHaveBeenCalledWith("{}");
     }),
   );
+
+  it.effect("preserves secure-storage write failures without exposing them in the message", () =>
+    Effect.gen(function* () {
+      const cause = new Error("credential vault path leaked");
+      vi.stubGlobal("window", {
+        desktopBridge: {
+          getConnectionCatalog: vi.fn().mockResolvedValue(null),
+          setConnectionCatalog: vi.fn().mockRejectedValue(cause),
+        },
+      });
+      const backend = makeCatalogBackend({} as IDBDatabase);
+
+      const error = yield* backend.write("{}").pipe(Effect.flip);
+
+      expect(error.cause).toMatchObject({
+        _tag: "ConnectionStorageOperationError",
+        operation: "save",
+        backend: "desktop-secure-storage",
+        cause,
+      });
+      expect(error.detail).toBe("Could not save local connection data.");
+      expect(error.message).not.toContain(cause.message);
+    }),
+  );
 });
diff --git a/apps/web/src/connection/storage.ts b/apps/web/src/connection/storage.ts
index d118a428ed7..57cf28cabaa 100644
--- a/apps/web/src/connection/storage.ts
+++ b/apps/web/src/connection/storage.ts
@@ -13,8 +13,11 @@ import {
 } from "@t3tools/client-runtime/platform";
 import { TokenStore } from "@t3tools/client-runtime/authorization";
 import {
+  ConnectionStorageOperationError,
   ConnectionTransientError,
   CredentialStore,
+  DesktopSecureStorageUnavailableError,
+  IndexedDbUnavailableError,
   ProfileStore,
 } from "@t3tools/client-runtime/connection";
 import {
@@ -60,37 +63,11 @@ const encodeStoredShellSnapshot = Schema.encodeEffect(StoredShellSnapshotJson);
 const decodeStoredThreadSnapshot = Schema.decodeUnknownEffect(StoredThreadSnapshotJson);
 const encodeStoredThreadSnapshot = Schema.encodeEffect(StoredThreadSnapshotJson);
 
-function catalogError(operation: string, cause: unknown) {
-  return new ConnectionTransientError({
-    reason: "remote-unavailable",
-    detail: `Could not ${operation} the local connection catalog: ${String(cause)}`,
-  });
-}
-
-function persistenceError(
-  operation:
-    | "list-targets"
-    | "register-connection"
-    | "remove-connection"
-    | "load-shell"
-    | "save-shell"
-    | "load-thread"
-    | "save-thread"
-    | "remove-thread"
-    | "clear-environment",
-  cause: unknown,
-) {
-  return new ConnectionPersistenceError({
-    operation,
-    message: `Could not ${operation.replaceAll("-", " ")}: ${String(cause)}`,
-  });
-}
-
 const openDatabase = Effect.fn("web.connectionStorage.openDatabase")(function* () {
   return yield* Effect.callback<IDBDatabase, ConnectionTransientError>((resume) => {
     if (typeof indexedDB === "undefined") {
       resume(
-        Effect.fail(catalogError("open", "IndexedDB is unavailable in this browser context.")),
+        Effect.fail(ConnectionTransientError.fromStorageFailure(new IndexedDbUnavailableError())),
       );
       return;
     }
@@ -106,8 +83,18 @@ const openDatabase = Effect.fn("web.connectionStorage.openDatabase")(function* (
         request.result.createObjectStore(THREAD_STORE_NAME);
       }
     });
-    request.addEventListener("error", () => {
-      resume(Effect.fail(catalogError("open", request.error ?? "Unknown IndexedDB error")));
+    request.addEventListener("error", (event) => {
+      resume(
+        Effect.fail(
+          ConnectionTransientError.fromStorageFailure(
+            new ConnectionStorageOperationError({
+              operation: "open",
+              backend: "indexed-db",
+              cause: request.error ?? event,
+            }),
+          ),
+        ),
+      );
     });
     request.addEventListener("success", () => {
       resume(Effect.succeed(request.result));
@@ -118,8 +105,20 @@ const openDatabase = Effect.fn("web.connectionStorage.openDatabase")(function* (
 function readDatabaseValue(database: IDBDatabase, storeName: string, key: IDBValidKey) {
   return Effect.callback<unknown, ConnectionTransientError>((resume) => {
     const request = database.transaction(storeName, "readonly").objectStore(storeName).get(key);
-    request.addEventListener("error", () => {
-      resume(Effect.fail(catalogError("read", request.error ?? "Unknown IndexedDB read error")));
+    request.addEventListener("error", (event) => {
+      resume(
+        Effect.fail(
+          ConnectionTransientError.fromStorageFailure(
+            new ConnectionStorageOperationError({
+              operation: "read",
+              backend: "indexed-db",
+              storeName,
+              key,
+              cause: request.error ?? event,
+            }),
+          ),
+        ),
+      );
     });
     request.addEventListener("success", () => {
       resume(Effect.succeed(request.result));
@@ -135,9 +134,19 @@ function writeDatabaseValue(
 ) {
   return Effect.callback<void, ConnectionTransientError>((resume) => {
     const transaction = database.transaction(storeName, "readwrite");
-    transaction.addEventListener("error", () => {
+    transaction.addEventListener("error", (event) => {
       resume(
-        Effect.fail(catalogError("write", transaction.error ?? "Unknown IndexedDB write error")),
+        Effect.fail(
+          ConnectionTransientError.fromStorageFailure(
+            new ConnectionStorageOperationError({
+              operation: "write",
+              backend: "indexed-db",
+              storeName,
+              key,
+              cause: transaction.error ?? event,
+            }),
+          ),
+        ),
       );
     });
     transaction.addEventListener("complete", () => {
@@ -150,9 +159,19 @@ function writeDatabaseValue(
 function removeDatabaseValue(database: IDBDatabase, storeName: string, key: IDBValidKey) {
   return Effect.callback<void, ConnectionTransientError>((resume) => {
     const transaction = database.transaction(storeName, "readwrite");
-    transaction.addEventListener("error", () => {
+    transaction.addEventListener("error", (event) => {
       resume(
-        Effect.fail(catalogError("remove", transaction.error ?? "Unknown IndexedDB remove error")),
+        Effect.fail(
+          ConnectionTransientError.fromStorageFailure(
+            new ConnectionStorageOperationError({
+              operation: "remove",
+              backend: "indexed-db",
+              storeName,
+              key,
+              cause: transaction.error ?? event,
+            }),
+          ),
+        ),
       );
     });
     transaction.addEventListener("complete", () => {
@@ -165,18 +184,36 @@ function removeDatabaseValue(database: IDBDatabase, storeName: string, key: IDBV
 function removeDatabaseValuesInRange(database: IDBDatabase, storeName: string, range: IDBKeyRange) {
   return Effect.callback<void, ConnectionTransientError>((resume) => {
     const transaction = database.transaction(storeName, "readwrite");
-    transaction.addEventListener("error", () => {
+    transaction.addEventListener("error", (event) => {
       resume(
-        Effect.fail(catalogError("remove", transaction.error ?? "Unknown IndexedDB cursor error")),
+        Effect.fail(
+          ConnectionTransientError.fromStorageFailure(
+            new ConnectionStorageOperationError({
+              operation: "remove",
+              backend: "indexed-db",
+              storeName,
+              cause: transaction.error ?? event,
+            }),
+          ),
+        ),
       );
     });
     transaction.addEventListener("complete", () => {
       resume(Effect.void);
     });
     const request = transaction.objectStore(storeName).openCursor(range);
-    request.addEventListener("error", () => {
+    request.addEventListener("error", (event) => {
       resume(
-        Effect.fail(catalogError("remove", request.error ?? "Unknown IndexedDB cursor error")),
+        Effect.fail(
+          ConnectionTransientError.fromStorageFailure(
+            new ConnectionStorageOperationError({
+              operation: "remove",
+              backend: "indexed-db",
+              storeName,
+              cause: request.error ?? event,
+            }),
+          ),
+        ),
       );
     });
     request.addEventListener("success", () => {
@@ -196,7 +233,15 @@ function threadCacheKey(environmentId: EnvironmentId, threadId: ThreadId) {
 
 const decodeCatalog = Effect.fn("web.connectionStorage.decodeCatalog")(function* (raw: string) {
   return yield* decodeConnectionCatalogDocument(raw).pipe(
-    Effect.mapError((cause) => catalogError("decode", cause)),
+    Effect.mapError((cause) =>
+      ConnectionTransientError.fromStorageFailure(
+        new ConnectionStorageOperationError({
+          operation: "decode",
+          backend: "schema",
+          cause,
+        }),
+      ),
+    ),
   );
 });
 
@@ -204,7 +249,15 @@ const encodeCatalog = Effect.fn("web.connectionStorage.encodeCatalog")(function*
   catalog: ConnectionCatalogDocumentType,
 ) {
   return yield* encodeConnectionCatalogDocument(catalog).pipe(
-    Effect.mapError((cause) => catalogError("encode", cause)),
+    Effect.mapError((cause) =>
+      ConnectionTransientError.fromStorageFailure(
+        new ConnectionStorageOperationError({
+          operation: "encode",
+          backend: "schema",
+          cause,
+        }),
+      ),
+    ),
   );
 });
 
@@ -220,20 +273,33 @@ export function makeCatalogBackend(database: IDBDatabase): CatalogBackend {
     return {
       read: Effect.tryPromise({
         try: () => bridge.getConnectionCatalog!(),
-        catch: (cause) => catalogError("load", cause),
+        catch: (cause) =>
+          ConnectionTransientError.fromStorageFailure(
+            new ConnectionStorageOperationError({
+              operation: "load",
+              backend: "desktop-secure-storage",
+              cause,
+            }),
+          ),
       }),
       write: (raw) =>
         Effect.tryPromise({
           try: () => bridge.setConnectionCatalog!(raw),
-          catch: (cause) => catalogError("save", cause),
+          catch: (cause) =>
+            ConnectionTransientError.fromStorageFailure(
+              new ConnectionStorageOperationError({
+                operation: "save",
+                backend: "desktop-secure-storage",
+                cause,
+              }),
+            ),
         }).pipe(
           Effect.flatMap((stored) =>
             stored
               ? Effect.void
               : Effect.fail(
-                  catalogError(
-                    "save",
-                    "Desktop secure storage is unavailable in this system context.",
+                  ConnectionTransientError.fromStorageFailure(
+                    new DesktopSecureStorageUnavailableError(),
                   ),
                 ),
           ),
@@ -273,31 +339,33 @@ export const makeCatalogStore = Effect.fn("web.connectionStorage.makeCatalogStor
     let catalog = EMPTY_CONNECTION_CATALOG_DOCUMENT;
     if (raw !== null && raw.trim() !== "") {
       catalog = yield* decodeCatalog(raw).pipe(
-        Effect.catch((error) =>
-          Effect.gen(function* () {
-            yield* Effect.logWarning("Discarding a corrupt web connection catalog.", {
-              error: error.message,
-            });
-            if (backend.quarantine !== undefined) {
-              yield* backend.quarantine(raw).pipe(
-                Effect.catch((cause) =>
-                  Effect.logWarning("Could not quarantine the corrupt web connection catalog.", {
-                    error: cause.message,
+        Effect.catchTags({
+          ConnectionTransientError: (error) =>
+            Effect.gen(function* () {
+              yield* Effect.logWarning("Discarding a corrupt web connection catalog.", { error });
+              if (backend.quarantine !== undefined) {
+                yield* backend.quarantine(raw).pipe(
+                  Effect.catchTags({
+                    ConnectionTransientError: (error) =>
+                      Effect.logWarning(
+                        "Could not quarantine the corrupt web connection catalog.",
+                        { error },
+                      ),
                   }),
-                ),
-              );
-            }
-            const encoded = yield* encodeCatalog(EMPTY_CONNECTION_CATALOG_DOCUMENT);
-            yield* backend.write(encoded).pipe(
-              Effect.catch((cause) =>
-                Effect.logWarning("Could not persist the recovered web connection catalog.", {
-                  error: cause.message,
+                );
+              }
+              const encoded = yield* encodeCatalog(EMPTY_CONNECTION_CATALOG_DOCUMENT);
+              yield* backend.write(encoded).pipe(
+                Effect.catchTags({
+                  ConnectionTransientError: (error) =>
+                    Effect.logWarning("Could not persist the recovered web connection catalog.", {
+                      error,
+                    }),
                 }),
-              ),
-            );
-            return EMPTY_CONNECTION_CATALOG_DOCUMENT;
-          }),
-        ),
+              );
+              return EMPTY_CONNECTION_CATALOG_DOCUMENT;
+            }),
+        }),
       );
     }
     yield* Ref.set(state, Option.some(catalog));
@@ -330,18 +398,45 @@ export const connectionStorageLayer = Layer.effectContext(
     const targetStore = ConnectionTargetStore.of({
       list: catalog.read.pipe(
         Effect.map((document) => document.targets),
-        Effect.mapError((cause) => persistenceError("list-targets", cause)),
+        Effect.mapError((cause) =>
+          ConnectionPersistenceError.fromStorageFailure({
+            operation: "list-targets",
+            fallbackStage: "read",
+            resource: "connection-catalog",
+            cause,
+          }),
+        ),
       ),
     });
     const registrationStore = ConnectionRegistrationStore.of({
       register: (registration) =>
         catalog
           .update((document) => registerConnectionInCatalog(document, registration))
-          .pipe(Effect.mapError((cause) => persistenceError("register-connection", cause))),
+          .pipe(
+            Effect.mapError((cause) =>
+              ConnectionPersistenceError.fromStorageFailure({
+                operation: "register-connection",
+                fallbackStage: "write",
+                resource: "connection-catalog",
+                environmentId: registration.target.environmentId,
+                cause,
+              }),
+            ),
+          ),
       remove: (target) =>
         catalog
           .update((document) => removeConnectionFromCatalog(document, target))
-          .pipe(Effect.mapError((cause) => persistenceError("remove-connection", cause))),
+          .pipe(
+            Effect.mapError((cause) =>
+              ConnectionPersistenceError.fromStorageFailure({
+                operation: "remove-connection",
+                fallbackStage: "write",
+                resource: "connection-catalog",
+                environmentId: target.environmentId,
+                cause,
+              }),
+            ),
+          ),
     });
     const profileStore = ProfileStore.make({
       get: (connectionId) =>
@@ -425,12 +520,31 @@ export const connectionStorageLayer = Layer.effectContext(
     const cacheStore = EnvironmentCacheStore.of({
       loadShell: (environmentId) =>
         readDatabaseValue(database, SHELL_STORE_NAME, environmentId).pipe(
+          Effect.mapError(
+            (cause) =>
+              new ConnectionPersistenceError({
+                operation: "load-shell",
+                stage: "read",
+                resource: "shell-cache",
+                environmentId,
+                cause,
+              }),
+          ),
           Effect.flatMap((raw) => {
             if (typeof raw !== "string") {
               return Effect.succeed(Option.none());
             }
             return decodeStoredShellSnapshot(raw).pipe(
-              Effect.mapError((cause) => persistenceError("load-shell", cause)),
+              Effect.mapError(
+                (cause) =>
+                  new ConnectionPersistenceError({
+                    operation: "load-shell",
+                    stage: "decode",
+                    resource: "shell-cache",
+                    environmentId,
+                    cause,
+                  }),
+              ),
               Effect.map((stored) =>
                 stored.environmentId === environmentId
                   ? Option.some(stored.snapshot)
@@ -438,11 +552,6 @@ export const connectionStorageLayer = Layer.effectContext(
               ),
             );
           }),
-          Effect.mapError((cause) =>
-            cause._tag === "ConnectionPersistenceError"
-              ? cause
-              : persistenceError("load-shell", cause),
-          ),
         ),
       saveShell: (environmentId, snapshot) =>
         Effect.gen(function* () {
@@ -450,27 +559,64 @@ export const connectionStorageLayer = Layer.effectContext(
             schemaVersion: SHELL_SNAPSHOT_CACHE_SCHEMA_VERSION,
             environmentId,
             snapshot,
-          }).pipe(Effect.mapError((cause) => persistenceError("save-shell", cause)));
-          yield* writeDatabaseValue(database, SHELL_STORE_NAME, environmentId, encoded);
-        }).pipe(
-          Effect.mapError((cause) =>
-            cause._tag === "ConnectionPersistenceError"
-              ? cause
-              : persistenceError("save-shell", cause),
-          ),
-        ),
+          }).pipe(
+            Effect.mapError(
+              (cause) =>
+                new ConnectionPersistenceError({
+                  operation: "save-shell",
+                  stage: "encode",
+                  resource: "shell-cache",
+                  environmentId,
+                  cause,
+                }),
+            ),
+          );
+          yield* writeDatabaseValue(database, SHELL_STORE_NAME, environmentId, encoded).pipe(
+            Effect.mapError(
+              (cause) =>
+                new ConnectionPersistenceError({
+                  operation: "save-shell",
+                  stage: "write",
+                  resource: "shell-cache",
+                  environmentId,
+                  cause,
+                }),
+            ),
+          );
+        }),
       loadThread: (environmentId, threadId) =>
         readDatabaseValue(
           database,
           THREAD_STORE_NAME,
           threadCacheKey(environmentId, threadId),
         ).pipe(
+          Effect.mapError(
+            (cause) =>
+              new ConnectionPersistenceError({
+                operation: "load-thread",
+                stage: "read",
+                resource: "thread-cache",
+                environmentId,
+                threadId,
+                cause,
+              }),
+          ),
           Effect.flatMap((raw) => {
             if (typeof raw !== "string") {
               return Effect.succeed(Option.none());
             }
             return decodeStoredThreadSnapshot(raw).pipe(
-              Effect.mapError((cause) => persistenceError("load-thread", cause)),
+              Effect.mapError(
+                (cause) =>
+                  new ConnectionPersistenceError({
+                    operation: "load-thread",
+                    stage: "decode",
+                    resource: "thread-cache",
+                    environmentId,
+                    threadId,
+                    cause,
+                  }),
+              ),
               Effect.map((stored) =>
                 stored.environmentId === environmentId && stored.threadId === threadId
                   ? Option.some(stored.thread)
@@ -478,11 +624,6 @@ export const connectionStorageLayer = Layer.effectContext(
               ),
             );
           }),
-          Effect.mapError((cause) =>
-            cause._tag === "ConnectionPersistenceError"
-              ? cause
-              : persistenceError("load-thread", cause),
-          ),
         ),
       saveThread: (environmentId, thread) =>
         Effect.gen(function* () {
@@ -491,38 +632,90 @@ export const connectionStorageLayer = Layer.effectContext(
             environmentId,
             threadId: thread.id,
             thread,
-          }).pipe(Effect.mapError((cause) => persistenceError("save-thread", cause)));
+          }).pipe(
+            Effect.mapError(
+              (cause) =>
+                new ConnectionPersistenceError({
+                  operation: "save-thread",
+                  stage: "encode",
+                  resource: "thread-cache",
+                  environmentId,
+                  threadId: thread.id,
+                  cause,
+                }),
+            ),
+          );
           yield* writeDatabaseValue(
             database,
             THREAD_STORE_NAME,
             threadCacheKey(environmentId, thread.id),
             encoded,
+          ).pipe(
+            Effect.mapError(
+              (cause) =>
+                new ConnectionPersistenceError({
+                  operation: "save-thread",
+                  stage: "write",
+                  resource: "thread-cache",
+                  environmentId,
+                  threadId: thread.id,
+                  cause,
+                }),
+            ),
           );
-        }).pipe(
-          Effect.mapError((cause) =>
-            cause._tag === "ConnectionPersistenceError"
-              ? cause
-              : persistenceError("save-thread", cause),
-          ),
-        ),
+        }),
       removeThread: (environmentId, threadId) =>
         removeDatabaseValue(
           database,
           THREAD_STORE_NAME,
           threadCacheKey(environmentId, threadId),
-        ).pipe(Effect.mapError((cause) => persistenceError("remove-thread", cause))),
+        ).pipe(
+          Effect.mapError(
+            (cause) =>
+              new ConnectionPersistenceError({
+                operation: "remove-thread",
+                stage: "remove",
+                resource: "thread-cache",
+                environmentId,
+                threadId,
+                cause,
+              }),
+          ),
+        ),
       clear: (environmentId) =>
         Effect.all(
           [
-            removeDatabaseValue(database, SHELL_STORE_NAME, environmentId),
+            removeDatabaseValue(database, SHELL_STORE_NAME, environmentId).pipe(
+              Effect.mapError(
+                (cause) =>
+                  new ConnectionPersistenceError({
+                    operation: "clear-environment",
+                    stage: "remove",
+                    resource: "shell-cache",
+                    environmentId,
+                    cause,
+                  }),
+              ),
+            ),
             removeDatabaseValuesInRange(
               database,
               THREAD_STORE_NAME,
               IDBKeyRange.bound(`${environmentId}:`, `${environmentId}:\uffff`),
+            ).pipe(
+              Effect.mapError(
+                (cause) =>
+                  new ConnectionPersistenceError({
+                    operation: "clear-environment",
+                    stage: "remove",
+                    resource: "thread-cache",
+                    environmentId,
+                    cause,
+                  }),
+              ),
             ),
           ],
           { concurrency: "unbounded", discard: true },
-        ).pipe(Effect.mapError((cause) => persistenceError("clear-environment", cause))),
+        ),
     });
 
     return Context.make(ConnectionTargetStore, targetStore).pipe(
diff --git a/apps/web/src/localApi.test.ts b/apps/web/src/localApi.test.ts
index 3379f5ed989..3332b76b615 100644
--- a/apps/web/src/localApi.test.ts
+++ b/apps/web/src/localApi.test.ts
@@ -62,17 +62,42 @@ afterEach(() => {
 
 describe("LocalApi", () => {
   it("keeps backend operations unavailable in the browser facade", async () => {
-    const { createLocalApi } = await import("./localApi");
+    const { createLocalApi, LocalBackendUnavailableError } = await import("./localApi");
     const api = createLocalApi();
 
-    await expect(api.server.getConfig()).rejects.toThrow(
-      "Local backend API is unavailable before a backend is paired.",
+    await expect(api.server.getConfig()).rejects.toEqual(
+      new LocalBackendUnavailableError({ operation: "get-config" }),
     );
-    await expect(api.shell.openInEditor("/tmp", "cursor")).rejects.toThrow(
-      "Local backend API is unavailable before a backend is paired.",
+    await expect(api.shell.openInEditor("/tmp", "cursor")).rejects.toEqual(
+      new LocalBackendUnavailableError({ operation: "open-in-editor" }),
     );
   });
 
+  it("preserves desktop bridge failures when opening external URLs", async () => {
+    const cause = new Error("shell rejected request");
+    const url =
+      "https://user:password@example.com/pull/42?access_token=signed-secret-token#private";
+    testWindow().desktopBridge = {
+      openExternal: vi.fn().mockRejectedValue(cause),
+    } as unknown as DesktopBridge;
+
+    const { createLocalApi } = await import("./localApi");
+    const promise = createLocalApi().shell.openExternal(url);
+
+    const error = await promise.catch((error: unknown) => error);
+    expect(error).toMatchObject({
+      _tag: "LocalExternalUrlOpenError",
+      urlHostname: "example.com",
+      urlLength: url.length,
+      urlProtocol: "https:",
+      cause,
+      message: `Unable to open an external URL for example.com through the desktop bridge (https:, input length ${url.length}).`,
+    });
+    expect(error).not.toHaveProperty("url");
+    expect(String(error)).not.toContain("user:password");
+    expect(String(error)).not.toContain("signed-secret-token");
+  });
+
   it("uses the browser context-menu fallback without a desktop bridge", async () => {
     showContextMenuFallbackMock.mockResolvedValue("rename");
     const { createLocalApi } = await import("./localApi");
diff --git a/apps/web/src/localApi.ts b/apps/web/src/localApi.ts
index 2fbf183f91b..0042906f7f6 100644
--- a/apps/web/src/localApi.ts
+++ b/apps/web/src/localApi.ts
@@ -1,4 +1,6 @@
 import type { ContextMenuItem, LocalApi } from "@t3tools/contracts";
+import { getUrlDiagnostics } from "@t3tools/shared/urlDiagnostics";
+import * as Schema from "effect/Schema";
 
 import { resetRequestLatencyStateForTests } from "./rpc/requestLatencyState";
 import { showContextMenuFallback } from "./contextMenuFallback";
@@ -6,8 +8,61 @@ import { readBrowserClientSettings, writeBrowserClientSettings } from "./clientP
 
 let cachedApi: LocalApi | undefined;
 
-function unavailableLocalBackendError(): Error {
-  return new Error("Local backend API is unavailable before a backend is paired.");
+export class LocalBackendUnavailableError extends Schema.TaggedErrorClass<LocalBackendUnavailableError>()(
+  "LocalBackendUnavailableError",
+  {
+    operation: Schema.Literals([
+      "open-in-editor",
+      "get-config",
+      "refresh-providers",
+      "update-provider",
+      "upsert-keybinding",
+      "remove-keybinding",
+      "get-settings",
+      "update-settings",
+      "discover-source-control",
+      "get-trace-diagnostics",
+      "get-process-diagnostics",
+      "get-process-resource-history",
+      "signal-process",
+    ]),
+  },
+) {
+  override get message(): string {
+    return `Local backend operation ${this.operation} is unavailable before a backend is paired.`;
+  }
+}
+
+export class LocalExternalUrlOpenError extends Schema.TaggedErrorClass<LocalExternalUrlOpenError>()(
+  "LocalExternalUrlOpenError",
+  {
+    urlHostname: Schema.NullOr(Schema.String),
+    urlLength: Schema.Number,
+    urlProtocol: Schema.NullOr(Schema.String),
+    cause: Schema.optional(Schema.Defect()),
+  },
+) {
+  override get message(): string {
+    return `Unable to open an external URL for ${this.urlHostname ?? "an unknown host"} through the desktop bridge (${this.urlProtocol ?? "unknown protocol"}, input length ${this.urlLength}).`;
+  }
+}
+
+export class LocalApiUnavailableError extends Schema.TaggedErrorClass<LocalApiUnavailableError>()(
+  "LocalApiUnavailableError",
+  {},
+) {
+  override get message(): string {
+    return "Local API is unavailable in the server runtime.";
+  }
+}
+
+function describeExternalUrl(url: string) {
+  const diagnostics = getUrlDiagnostics(url);
+  return {
+    urlHostname: diagnostics.hostname ?? null,
+    urlLength: diagnostics.inputLength,
+    urlProtocol: diagnostics.protocol ?? null,
+  };
 }
 
 function createBrowserLocalApi(): LocalApi {
@@ -25,12 +80,21 @@ function createBrowserLocalApi(): LocalApi {
       },
     },
     shell: {
-      openInEditor: () => Promise.reject(unavailableLocalBackendError()),
+      openInEditor: () =>
+        Promise.reject(new LocalBackendUnavailableError({ operation: "open-in-editor" })),
       openExternal: async (url) => {
         if (window.desktopBridge) {
-          const opened = await window.desktopBridge.openExternal(url);
+          let opened: boolean;
+          try {
+            opened = await window.desktopBridge.openExternal(url);
+          } catch (cause) {
+            throw new LocalExternalUrlOpenError({
+              ...describeExternalUrl(url),
+              cause,
+            });
+          }
           if (!opened) {
-            throw new Error("Unable to open link.");
+            throw new LocalExternalUrlOpenError(describeExternalUrl(url));
           }
           return;
         }
@@ -64,18 +128,32 @@ function createBrowserLocalApi(): LocalApi {
       },
     },
     server: {
-      getConfig: () => Promise.reject(unavailableLocalBackendError()),
-      refreshProviders: () => Promise.reject(unavailableLocalBackendError()),
-      updateProvider: () => Promise.reject(unavailableLocalBackendError()),
-      upsertKeybinding: () => Promise.reject(unavailableLocalBackendError()),
-      removeKeybinding: () => Promise.reject(unavailableLocalBackendError()),
-      getSettings: () => Promise.reject(unavailableLocalBackendError()),
-      updateSettings: () => Promise.reject(unavailableLocalBackendError()),
-      discoverSourceControl: () => Promise.reject(unavailableLocalBackendError()),
-      getTraceDiagnostics: () => Promise.reject(unavailableLocalBackendError()),
-      getProcessDiagnostics: () => Promise.reject(unavailableLocalBackendError()),
-      getProcessResourceHistory: () => Promise.reject(unavailableLocalBackendError()),
-      signalProcess: () => Promise.reject(unavailableLocalBackendError()),
+      getConfig: () =>
+        Promise.reject(new LocalBackendUnavailableError({ operation: "get-config" })),
+      refreshProviders: () =>
+        Promise.reject(new LocalBackendUnavailableError({ operation: "refresh-providers" })),
+      updateProvider: () =>
+        Promise.reject(new LocalBackendUnavailableError({ operation: "update-provider" })),
+      upsertKeybinding: () =>
+        Promise.reject(new LocalBackendUnavailableError({ operation: "upsert-keybinding" })),
+      removeKeybinding: () =>
+        Promise.reject(new LocalBackendUnavailableError({ operation: "remove-keybinding" })),
+      getSettings: () =>
+        Promise.reject(new LocalBackendUnavailableError({ operation: "get-settings" })),
+      updateSettings: () =>
+        Promise.reject(new LocalBackendUnavailableError({ operation: "update-settings" })),
+      discoverSourceControl: () =>
+        Promise.reject(new LocalBackendUnavailableError({ operation: "discover-source-control" })),
+      getTraceDiagnostics: () =>
+        Promise.reject(new LocalBackendUnavailableError({ operation: "get-trace-diagnostics" })),
+      getProcessDiagnostics: () =>
+        Promise.reject(new LocalBackendUnavailableError({ operation: "get-process-diagnostics" })),
+      getProcessResourceHistory: () =>
+        Promise.reject(
+          new LocalBackendUnavailableError({ operation: "get-process-resource-history" }),
+        ),
+      signalProcess: () =>
+        Promise.reject(new LocalBackendUnavailableError({ operation: "signal-process" })),
     },
   };
 }
@@ -100,7 +178,7 @@ export function readLocalApi(): LocalApi | undefined {
 export function ensureLocalApi(): LocalApi {
   const api = readLocalApi();
   if (!api) {
-    throw new Error("Local API not found");
+    throw new LocalApiUnavailableError();
   }
   return api;
 }
diff --git a/infra/relay/src/environments/EnvironmentConnector.test.ts b/infra/relay/src/environments/EnvironmentConnector.test.ts
index 63f12379870..11ad7f9944c 100644
--- a/infra/relay/src/environments/EnvironmentConnector.test.ts
+++ b/infra/relay/src/environments/EnvironmentConnector.test.ts
@@ -56,6 +56,10 @@ const decodeMintRequestBody = Schema.decodeUnknownSync(
 const isEnvironmentConnectNotAuthorized = Schema.is(
   EnvironmentConnector.EnvironmentConnectNotAuthorized,
 );
+const isEnvironmentMintRequestFailed = Schema.is(EnvironmentConnector.EnvironmentMintRequestFailed);
+const isEnvironmentMintResponseInvalid = Schema.is(
+  EnvironmentConnector.EnvironmentMintResponseInvalid,
+);
 
 function requestBodyText(request: HttpClientRequest.HttpClientRequest): string {
   return request.body._tag === "Uint8Array" ? new TextDecoder().decode(request.body.body) : "{}";
@@ -227,6 +231,55 @@ function makeLinks(
 }
 
 describe("EnvironmentConnector", () => {
+  it("redacts endpoint secrets while preserving mapped causes", () => {
+    const httpBaseUrl =
+      "https://environment-user:environment-password@env.example.test/private/workspace?access_token=environment-secret#environment-fragment";
+    const cause = new Error("mint failed");
+    const requestError = EnvironmentConnector.EnvironmentMintRequestFailed.fromEndpoint({
+      userId: "user_123",
+      environmentId: "env-connector-test",
+      operation: "connect",
+      stage: "send_request",
+      httpBaseUrl,
+      cause,
+    });
+    const responseError = EnvironmentConnector.EnvironmentMintResponseInvalid.fromEndpoint({
+      userId: "user_123",
+      environmentId: "env-connector-test",
+      operation: "connect",
+      httpBaseUrl,
+      reason: "proof_verification_failed",
+      cause,
+    });
+    const timeoutError = EnvironmentConnector.EnvironmentMintRequestTimedOut.fromEndpoint({
+      userId: "user_123",
+      environmentId: "env-connector-test",
+      httpBaseUrl,
+      timeoutMs: EnvironmentConnector.ENVIRONMENT_MINT_REQUEST_TIMEOUT_MS,
+    });
+
+    for (const error of [requestError, responseError, timeoutError]) {
+      expect(error).toMatchObject({
+        httpBaseUrlInputLength: httpBaseUrl.length,
+        httpBaseUrlProtocol: "https:",
+        httpBaseUrlHostname: "env.example.test",
+      });
+      const serialized = JSON.stringify(error);
+      for (const secret of [
+        "environment-user",
+        "environment-password",
+        "/private/workspace",
+        "environment-secret",
+        "environment-fragment",
+      ]) {
+        expect(serialized).not.toContain(secret);
+        expect(error.message).not.toContain(secret);
+      }
+    }
+    expect(requestError.cause).toBe(cause);
+    expect(responseError.cause).toBe(cause);
+  });
+
   it.effect("loads the environment link and managed allocation concurrently", () =>
     Effect.gen(function* () {
       const started = yield* Ref.make(0);
@@ -344,6 +397,9 @@ describe("EnvironmentConnector", () => {
             operation: "status",
             reason: "endpoint_provider_not_managed",
           });
+          expect(result.failure.message).toBe(
+            "Environment 'env-connector-test' is not authorized for status (endpoint_provider_not_managed).",
+          );
         }
       }
       expect(requestCount).toBe(0);
@@ -401,24 +457,57 @@ describe("EnvironmentConnector", () => {
       const resolutionSpan = spans.find(
         (span) => span.name === "relay.environment_connector.resolve_managed_endpoint",
       );
-      expect(Object.fromEntries(resolutionSpan?.attributes ?? [])).toMatchObject({
+      const resolutionAttributes = Object.fromEntries(resolutionSpan?.attributes ?? []);
+      expect(resolutionAttributes).toMatchObject({
         "relay.authorization.allocation_hostname": "env.example.test",
         "relay.authorization.allocation_has_ready_at": true,
         "relay.authorization.allocation_has_tunnel_id": true,
         "relay.authorization.allocation_has_dns_record_id": true,
-        "relay.authorization.linked_http_base_url": "https://attacker.example.test/",
-        "relay.authorization.linked_ws_base_url": "wss://attacker.example.test/ws",
-        "relay.authorization.resolved_http_base_url": "https://env.example.test/",
-        "relay.authorization.resolved_ws_base_url": "wss://env.example.test/ws",
+        "relay.authorization.linked_http_base_url.input_length":
+          "https://attacker-user:attacker-password@attacker.example.test/private/workspace?access_token=attacker-secret#attacker-fragment"
+            .length,
+        "relay.authorization.linked_http_base_url.protocol": "https:",
+        "relay.authorization.linked_http_base_url.hostname": "attacker.example.test",
+        "relay.authorization.linked_ws_base_url.input_length":
+          "wss://socket-user:socket-password@attacker.example.test/private/socket?access_token=socket-secret#socket-fragment"
+            .length,
+        "relay.authorization.linked_ws_base_url.protocol": "wss:",
+        "relay.authorization.linked_ws_base_url.hostname": "attacker.example.test",
+        "relay.authorization.resolved_http_base_url.input_length": "https://env.example.test/"
+          .length,
+        "relay.authorization.resolved_http_base_url.protocol": "https:",
+        "relay.authorization.resolved_http_base_url.hostname": "env.example.test",
+        "relay.authorization.resolved_ws_base_url.input_length": "wss://env.example.test/ws".length,
+        "relay.authorization.resolved_ws_base_url.protocol": "wss:",
+        "relay.authorization.resolved_ws_base_url.hostname": "env.example.test",
       });
+      const serializedAttributes = Object.entries(resolutionAttributes)
+        .flatMap(([key, value]) => [key, String(value)])
+        .join("\n");
+      for (const secret of [
+        "attacker-user",
+        "attacker-password",
+        "/private/workspace",
+        "attacker-secret",
+        "attacker-fragment",
+        "socket-user",
+        "socket-password",
+        "/private/socket",
+        "socket-secret",
+        "socket-fragment",
+      ]) {
+        expect(serializedAttributes).not.toContain(secret);
+      }
       expect(requestCount).toBe(0);
     }).pipe(
       Effect.provide(
         connectorTestLayer(execute, {
           links: makeLinks({
             endpoint: {
-              httpBaseUrl: "https://attacker.example.test/",
-              wsBaseUrl: "wss://attacker.example.test/ws",
+              httpBaseUrl:
+                "https://attacker-user:attacker-password@attacker.example.test/private/workspace?access_token=attacker-secret#attacker-fragment",
+              wsBaseUrl:
+                "wss://socket-user:socket-password@attacker.example.test/private/socket?access_token=socket-secret#socket-fragment",
               providerKind: "cloudflare_tunnel",
             },
           }),
@@ -517,6 +606,7 @@ describe("EnvironmentConnector", () => {
           Response.json(
             {
               _tag: "EnvironmentHttpInternalServerError",
+              operation: "answer_cloud_health_request",
               message: "Environment is unavailable.",
             },
             { status: 500 },
@@ -700,7 +790,7 @@ describe("EnvironmentConnector", () => {
 
     return Effect.gen(function* () {
       const connector = yield* EnvironmentConnector.EnvironmentConnector;
-      const result = yield* Effect.exit(
+      const result = yield* Effect.result(
         connector.connect({
           userId: "user_123",
           environmentId: "env-connector-test",
@@ -708,9 +798,21 @@ describe("EnvironmentConnector", () => {
         }),
       );
 
-      expect(result._tag).toBe("Failure");
-      if (result._tag === "Failure") {
-        expect(result.cause.toString()).toContain("EnvironmentMintResponseInvalid");
+      expect(Result.isFailure(result)).toBe(true);
+      if (Result.isFailure(result)) {
+        expect(isEnvironmentMintResponseInvalid(result.failure)).toBe(true);
+        if (isEnvironmentMintResponseInvalid(result.failure)) {
+          expect(result.failure).toMatchObject({
+            userId: "user_123",
+            environmentId: "env-connector-test",
+            operation: "connect",
+            httpBaseUrlInputLength: "https://env.example.test/".length,
+            httpBaseUrlProtocol: "https:",
+            httpBaseUrlHostname: "env.example.test",
+            reason: "proof_verification_failed",
+            cause: { _tag: "RelayJwtError" },
+          });
+        }
       }
     }).pipe(Effect.provide(connectorTestLayer(execute)));
   });
@@ -780,6 +882,52 @@ describe("EnvironmentConnector", () => {
     }).pipe(Effect.provide(connectorTestLayer(execute)));
   });
 
+  it.effect("preserves context and cause when the mint request fails", () => {
+    const execute = (request: HttpClientRequest.HttpClientRequest) =>
+      Effect.succeed(
+        HttpClientResponse.fromWeb(
+          request,
+          Response.json(
+            {
+              _tag: "EnvironmentHttpInternalServerError",
+              message: "Environment is unavailable.",
+            },
+            { status: 500 },
+          ),
+        ),
+      );
+
+    return Effect.gen(function* () {
+      const connector = yield* EnvironmentConnector.EnvironmentConnector;
+      const result = yield* Effect.result(
+        connector.connect({
+          userId: "user_123",
+          environmentId: "env-connector-test",
+          clientProofKeyThumbprint: "client-proof-key-thumbprint",
+          deviceId: "device-123",
+        }),
+      );
+
+      expect(Result.isFailure(result)).toBe(true);
+      if (Result.isFailure(result)) {
+        expect(isEnvironmentMintRequestFailed(result.failure)).toBe(true);
+        if (isEnvironmentMintRequestFailed(result.failure)) {
+          expect(result.failure).toMatchObject({
+            userId: "user_123",
+            environmentId: "env-connector-test",
+            operation: "connect",
+            stage: "send_request",
+            httpBaseUrlInputLength: "https://env.example.test/".length,
+            httpBaseUrlProtocol: "https:",
+            httpBaseUrlHostname: "env.example.test",
+            deviceId: "device-123",
+            cause: { _tag: "EnvironmentHttpInternalServerError" },
+          });
+        }
+      }
+    }).pipe(Effect.provide(connectorTestLayer(execute)));
+  });
+
   it.effect("times out hung managed endpoint mint requests", () => {
     let resolveRequestStarted: (() => void) | undefined;
     const requestStarted = new Promise<void>((resolve) => {
@@ -810,7 +958,11 @@ describe("EnvironmentConnector", () => {
       if (Result.isFailure(result)) {
         expect(result.failure._tag).toBe("EnvironmentMintRequestTimedOut");
         expect(result.failure).toMatchObject({
+          userId: "user_123",
           environmentId: "env-connector-test",
+          httpBaseUrlInputLength: "https://env.example.test/".length,
+          httpBaseUrlProtocol: "https:",
+          httpBaseUrlHostname: "env.example.test",
           timeoutMs: EnvironmentConnector.ENVIRONMENT_MINT_REQUEST_TIMEOUT_MS,
         });
       }
diff --git a/infra/relay/src/environments/EnvironmentConnector.ts b/infra/relay/src/environments/EnvironmentConnector.ts
index db662aee94d..fd72fda44f4 100644
--- a/infra/relay/src/environments/EnvironmentConnector.ts
+++ b/infra/relay/src/environments/EnvironmentConnector.ts
@@ -26,6 +26,7 @@ import {
   verifyRelayJwt,
 } from "@t3tools/shared/relayJwt";
 import { stableStringify } from "@t3tools/shared/relaySigning";
+import { getUrlDiagnostics } from "@t3tools/shared/urlDiagnostics";
 import * as Context from "effect/Context";
 import * as Crypto from "effect/Crypto";
 import * as DateTime from "effect/DateTime";
@@ -57,29 +58,6 @@ export const EnvironmentConnectNotAuthorizedReason = Schema.Literals([
 export type EnvironmentConnectNotAuthorizedReason =
   typeof EnvironmentConnectNotAuthorizedReason.Type;
 
-function environmentConnectNotAuthorizedReasonMessage(
-  reason: EnvironmentConnectNotAuthorizedReason,
-): string {
-  switch (reason) {
-    case "client_proof_key_thumbprint_missing":
-      return "the client proof key thumbprint is missing";
-    case "environment_link_not_found":
-      return "no active environment link was found";
-    case "endpoint_provider_not_managed":
-      return "the linked endpoint is not relay-managed";
-    case "managed_endpoint_allocation_not_found":
-      return "no managed endpoint allocation was found";
-    case "managed_endpoint_base_domain_not_configured":
-      return "the managed endpoint base domain is not configured";
-    case "managed_endpoint_allocation_not_ready":
-      return "the managed endpoint allocation is incomplete";
-    case "managed_endpoint_hostname_invalid":
-      return "the managed endpoint hostname is invalid";
-    case "managed_endpoint_mismatch":
-      return "the linked endpoint does not match its managed allocation";
-  }
-}
-
 export class EnvironmentConnectNotAuthorized extends Schema.TaggedErrorClass<EnvironmentConnectNotAuthorized>()(
   "EnvironmentConnectNotAuthorized",
   {
@@ -89,44 +67,144 @@ export class EnvironmentConnectNotAuthorized extends Schema.TaggedErrorClass<Env
   },
 ) {
   override get message(): string {
-    return `Environment '${this.environmentId}' is not authorized for ${this.operation}: ${environmentConnectNotAuthorizedReasonMessage(this.reason)}`;
+    return `Environment '${this.environmentId}' is not authorized for ${this.operation} (${this.reason}).`;
   }
 }
 
+const httpBaseUrlDiagnosticSchema = {
+  httpBaseUrlInputLength: Schema.Number,
+  httpBaseUrlProtocol: Schema.optionalKey(Schema.String),
+  httpBaseUrlHostname: Schema.optionalKey(Schema.String),
+} as const;
+
+function httpBaseUrlDiagnosticFields(httpBaseUrl: string) {
+  const diagnostics = getUrlDiagnostics(httpBaseUrl);
+  return {
+    httpBaseUrlInputLength: diagnostics.inputLength,
+    ...(diagnostics.protocol === undefined ? {} : { httpBaseUrlProtocol: diagnostics.protocol }),
+    ...(diagnostics.hostname === undefined ? {} : { httpBaseUrlHostname: diagnostics.hostname }),
+  };
+}
+
+function urlDiagnosticSpanAttributes(prefix: string, input: string) {
+  const diagnostics = getUrlDiagnostics(input);
+  return {
+    [`${prefix}.input_length`]: diagnostics.inputLength,
+    ...(diagnostics.protocol === undefined ? {} : { [`${prefix}.protocol`]: diagnostics.protocol }),
+    ...(diagnostics.hostname === undefined ? {} : { [`${prefix}.hostname`]: diagnostics.hostname }),
+  };
+}
+
 export class EnvironmentMintRequestFailed extends Schema.TaggedErrorClass<EnvironmentMintRequestFailed>()(
   "EnvironmentMintRequestFailed",
   {
+    userId: Schema.String,
     environmentId: Schema.String,
     operation: Schema.Literals(["connect", "status"]),
+    stage: Schema.Literals(["generate_nonce", "generate_request_id", "sign_proof", "send_request"]),
+    ...httpBaseUrlDiagnosticSchema,
+    deviceId: Schema.optional(Schema.String),
     cause: Schema.Defect(),
   },
 ) {
+  static fromEndpoint(input: {
+    readonly userId: string;
+    readonly environmentId: string;
+    readonly operation: "connect" | "status";
+    readonly stage: "generate_nonce" | "generate_request_id" | "sign_proof" | "send_request";
+    readonly httpBaseUrl: string;
+    readonly deviceId?: string;
+    readonly cause: unknown;
+  }): EnvironmentMintRequestFailed {
+    const { httpBaseUrl, ...context } = input;
+    return new EnvironmentMintRequestFailed({
+      ...context,
+      ...httpBaseUrlDiagnosticFields(httpBaseUrl),
+    });
+  }
+
   override get message(): string {
-    return `Environment '${this.environmentId}' ${this.operation} request failed`;
+    return `Environment '${this.environmentId}' ${this.operation} request failed during ${this.stage}`;
   }
 }
 
 export class EnvironmentMintRequestTimedOut extends Schema.TaggedErrorClass<EnvironmentMintRequestTimedOut>()(
   "EnvironmentMintRequestTimedOut",
   {
+    userId: Schema.String,
     environmentId: Schema.String,
+    ...httpBaseUrlDiagnosticSchema,
+    deviceId: Schema.optional(Schema.String),
     timeoutMs: Schema.Number,
   },
 ) {
+  static fromEndpoint(input: {
+    readonly userId: string;
+    readonly environmentId: string;
+    readonly httpBaseUrl: string;
+    readonly deviceId?: string;
+    readonly timeoutMs: number;
+  }): EnvironmentMintRequestTimedOut {
+    const { httpBaseUrl, ...context } = input;
+    return new EnvironmentMintRequestTimedOut({
+      ...context,
+      ...httpBaseUrlDiagnosticFields(httpBaseUrl),
+    });
+  }
+
   override get message(): string {
     return `Environment '${this.environmentId}' mint request timed out after ${this.timeoutMs}ms`;
   }
 }
 
+export const EnvironmentMintResponseInvalidReason = Schema.Literals([
+  "environment_public_key_missing",
+  "proof_verification_failed",
+  "response_environment_id_mismatch",
+  "proof_environment_id_mismatch",
+  "request_nonce_mismatch",
+  "client_proof_key_thumbprint_mismatch",
+  "credential_mismatch",
+  "expires_at_invalid",
+  "expires_at_mismatch",
+  "status_mismatch",
+  "checked_at_invalid",
+  "checked_at_mismatch",
+  "descriptor_mismatch",
+  "checked_at_out_of_range",
+]);
+export type EnvironmentMintResponseInvalidReason = typeof EnvironmentMintResponseInvalidReason.Type;
+
 export class EnvironmentMintResponseInvalid extends Schema.TaggedErrorClass<EnvironmentMintResponseInvalid>()(
   "EnvironmentMintResponseInvalid",
   {
+    userId: Schema.String,
     environmentId: Schema.String,
     operation: Schema.Literals(["connect", "status"]),
+    ...httpBaseUrlDiagnosticSchema,
+    deviceId: Schema.optional(Schema.String),
+    reason: EnvironmentMintResponseInvalidReason,
+    cause: Schema.optional(Schema.Defect()),
   },
 ) {
+  static fromEndpoint(input: {
+    readonly userId: string;
+    readonly environmentId: string;
+    readonly operation: "connect" | "status";
+    readonly httpBaseUrl: string;
+    readonly deviceId?: string;
+    readonly reason: EnvironmentMintResponseInvalidReason;
+    readonly cause?: unknown;
+  }): EnvironmentMintResponseInvalid {
+    const { httpBaseUrl, ...context } = input;
+    return new EnvironmentMintResponseInvalid({
+      ...context,
+      ...httpBaseUrlDiagnosticFields(httpBaseUrl),
+    });
+  }
+
   override get message(): string {
-    return `Environment '${this.environmentId}' returned an invalid ${this.operation} response`;
+    return `Environment '${this.environmentId}' returned an invalid ${this.operation} response (${this.reason})`;
   }
 }
 
@@ -210,17 +288,24 @@ const verifyWithEnvironmentKeys = Effect.fnUntraced(function* <A, E>(input: {
   readonly decodePayload: (input: unknown) => Effect.Effect<A, E>;
 }) {
   const { decodePayload, ...rest } = input;
+  let lastFailure: { readonly cause: unknown } | undefined;
   for (const publicKey of input.environmentPublicKeys) {
-    const proof = yield* verifyRelayJwt({ ...rest, publicKey }).pipe(
+    const result = yield* verifyRelayJwt({ ...rest, publicKey }).pipe(
       Effect.flatMap(decodePayload),
-      Effect.option,
+      Effect.match({
+        onFailure: (cause) => ({ _tag: "Failure" as const, cause }),
+        onSuccess: (proof) => ({ _tag: "Success" as const, proof }),
+      }),
     );
-    if (Option.isSome(proof)) {
-      return proof.value;
+    if (result._tag === "Success") {
+      return result;
     }
+    lastFailure = result;
     // A linked environment can have rotated keys; try the remaining active keys.
   }
-  return null;
+  return lastFailure
+    ? { _tag: "Failure" as const, cause: lastFailure.cause }
+    : { _tag: "MissingPublicKey" as const };
 });
 
 function verifyEnvironmentResponse(input: {
@@ -241,18 +326,35 @@ function verifyEnvironmentResponse(input: {
     environmentPublicKeys: input.environmentPublicKeys,
     decodePayload: decodeMintResponseProof,
   }).pipe(
-    Effect.map(
-      (proof) =>
-        proof !== null &&
-        proof.environmentId === input.environmentId &&
-        proof.requestNonce === input.requestNonce &&
-        proof.clientProofKeyThumbprint === input.clientProofKeyThumbprint &&
-        proof.credential === input.response.credential &&
-        Option.match(DateTime.make(input.response.expiresAt), {
-          onNone: () => false,
-          onSome: (expiresAt) => Math.floor(expiresAt.epochMilliseconds / 1_000) === proof.exp,
-        }),
-    ),
+    Effect.map((verification) => {
+      if (verification._tag === "MissingPublicKey") {
+        return { reason: "environment_public_key_missing" as const };
+      }
+      if (verification._tag === "Failure") {
+        return { reason: "proof_verification_failed" as const, cause: verification.cause };
+      }
+      const proof = verification.proof;
+      if (proof.environmentId !== input.environmentId) {
+        return { reason: "proof_environment_id_mismatch" as const };
+      }
+      if (proof.requestNonce !== input.requestNonce) {
+        return { reason: "request_nonce_mismatch" as const };
+      }
+      if (proof.clientProofKeyThumbprint !== input.clientProofKeyThumbprint) {
+        return { reason: "client_proof_key_thumbprint_mismatch" as const };
+      }
+      if (proof.credential !== input.response.credential) {
+        return { reason: "credential_mismatch" as const };
+      }
+      const expiresAt = DateTime.make(input.response.expiresAt);
+      if (Option.isNone(expiresAt)) {
+        return { reason: "expires_at_invalid" as const };
+      }
+      if (Math.floor(expiresAt.value.epochMilliseconds / 1_000) !== proof.exp) {
+        return { reason: "expires_at_mismatch" as const };
+      }
+      return null;
+    }),
   );
 }
 
@@ -274,28 +376,45 @@ function verifyEnvironmentHealthResponse(input: {
     environmentPublicKeys: input.environmentPublicKeys,
     decodePayload: decodeHealthResponseProof,
   }).pipe(
-    Effect.map((proof) => {
-      if (
-        proof === null ||
-        input.response.environmentId !== input.environmentId ||
-        proof.environmentId !== input.environmentId ||
-        proof.requestNonce !== input.requestNonce ||
-        proof.status !== input.response.status ||
-        proof.checkedAt !== input.response.checkedAt ||
-        stableStringify(proof.descriptor) !== stableStringify(input.response.descriptor)
-      ) {
-        return false;
+    Effect.map((verification) => {
+      if (verification._tag === "MissingPublicKey") {
+        return { reason: "environment_public_key_missing" as const };
+      }
+      if (verification._tag === "Failure") {
+        return { reason: "proof_verification_failed" as const, cause: verification.cause };
+      }
+      const proof = verification.proof;
+      if (input.response.environmentId !== input.environmentId) {
+        return { reason: "response_environment_id_mismatch" as const };
+      }
+      if (proof.environmentId !== input.environmentId) {
+        return { reason: "proof_environment_id_mismatch" as const };
+      }
+      if (proof.requestNonce !== input.requestNonce) {
+        return { reason: "request_nonce_mismatch" as const };
+      }
+      if (proof.status !== input.response.status) {
+        return { reason: "status_mismatch" as const };
+      }
+      if (proof.checkedAt !== input.response.checkedAt) {
+        return { reason: "checked_at_mismatch" as const };
+      }
+      if (stableStringify(proof.descriptor) !== stableStringify(input.response.descriptor)) {
+        return { reason: "descriptor_mismatch" as const };
       }
       const checkedAt = DateTime.make(input.response.checkedAt);
       if (Option.isNone(checkedAt)) {
-        return false;
+        return { reason: "checked_at_invalid" as const };
       }
-      return (
-        checkedAt.value.epochMilliseconds >=
-          input.requestIssuedAt.epochMilliseconds - ENVIRONMENT_HEALTH_CLOCK_SKEW_MILLIS &&
-        checkedAt.value.epochMilliseconds <=
+      if (
+        checkedAt.value.epochMilliseconds <
+          input.requestIssuedAt.epochMilliseconds - ENVIRONMENT_HEALTH_CLOCK_SKEW_MILLIS ||
+        checkedAt.value.epochMilliseconds >
           input.now.epochMilliseconds + ENVIRONMENT_HEALTH_CLOCK_SKEW_MILLIS
-      );
+      ) {
+        return { reason: "checked_at_out_of_range" as const };
+      }
+      return null;
     }),
   );
 }
@@ -384,12 +503,24 @@ const make = Effect.gen(function* () {
       ) {
         yield* Effect.annotateCurrentSpan({
           ...allocationAttributes,
-          "relay.authorization.linked_http_base_url": input.link.endpoint.httpBaseUrl,
-          "relay.authorization.linked_ws_base_url": input.link.endpoint.wsBaseUrl,
+          ...urlDiagnosticSpanAttributes(
+            "relay.authorization.linked_http_base_url",
+            input.link.endpoint.httpBaseUrl,
+          ),
+          ...urlDiagnosticSpanAttributes(
+            "relay.authorization.linked_ws_base_url",
+            input.link.endpoint.wsBaseUrl,
+          ),
           ...(endpoint
             ? {
-                "relay.authorization.resolved_http_base_url": endpoint.httpBaseUrl,
-                "relay.authorization.resolved_ws_base_url": endpoint.wsBaseUrl,
+                ...urlDiagnosticSpanAttributes(
+                  "relay.authorization.resolved_http_base_url",
+                  endpoint.httpBaseUrl,
+                ),
+                ...urlDiagnosticSpanAttributes(
+                  "relay.authorization.resolved_ws_base_url",
+                  endpoint.wsBaseUrl,
+                ),
               }
             : {}),
         });
@@ -431,13 +562,15 @@ const make = Effect.gen(function* () {
       const now = yield* DateTime.now;
       const expiresAt = DateTime.add(now, { minutes: 2 });
       const nonce = yield* crypto.randomUUIDv4.pipe(
-        Effect.mapError(
-          (cause) =>
-            new EnvironmentMintRequestFailed({
-              environmentId: input.environmentId,
-              operation: "status",
-              cause,
-            }),
+        Effect.mapError((cause) =>
+          EnvironmentMintRequestFailed.fromEndpoint({
+            userId: input.userId,
+            environmentId: input.environmentId,
+            operation: "status",
+            stage: "generate_nonce",
+            httpBaseUrl: endpoint.httpBaseUrl,
+            cause,
+          }),
         ),
       );
       const payload = {
@@ -445,13 +578,15 @@ const make = Effect.gen(function* () {
         aud: `t3-env:${link.environmentId}`,
         sub: input.userId,
         jti: yield* crypto.randomUUIDv4.pipe(
-          Effect.mapError(
-            (cause) =>
-              new EnvironmentMintRequestFailed({
-                environmentId: input.environmentId,
-                operation: "status",
-                cause,
-              }),
+          Effect.mapError((cause) =>
+            EnvironmentMintRequestFailed.fromEndpoint({
+              userId: input.userId,
+              environmentId: input.environmentId,
+              operation: "status",
+              stage: "generate_request_id",
+              httpBaseUrl: endpoint.httpBaseUrl,
+              cause,
+            }),
           ),
         ),
         iat: Math.floor(now.epochMilliseconds / 1_000),
@@ -465,13 +600,15 @@ const make = Effect.gen(function* () {
         typ: RELAY_HEALTH_REQUEST_TYP,
         payload,
       }).pipe(
-        Effect.mapError(
-          (cause) =>
-            new EnvironmentMintRequestFailed({
-              environmentId: input.environmentId,
-              operation: "status",
-              cause,
-            }),
+        Effect.mapError((cause) =>
+          EnvironmentMintRequestFailed.fromEndpoint({
+            userId: input.userId,
+            environmentId: input.environmentId,
+            operation: "status",
+            stage: "sign_proof",
+            httpBaseUrl: endpoint.httpBaseUrl,
+            cause,
+          }),
         ),
       );
       const checkedAt = DateTime.formatIso(now);
@@ -492,7 +629,7 @@ const make = Effect.gen(function* () {
         });
         yield* Effect.logWarning("Managed endpoint health request timed out", {
           environmentId: link.environmentId,
-          endpoint: endpoint.httpBaseUrl,
+          ...httpBaseUrlDiagnosticFields(endpoint.httpBaseUrl),
           traceId,
         });
         return {
@@ -513,7 +650,7 @@ const make = Effect.gen(function* () {
         });
         yield* Effect.logWarning("Managed endpoint health request failed", {
           environmentId: link.environmentId,
-          endpoint: endpoint.httpBaseUrl,
+          ...httpBaseUrlDiagnosticFields(endpoint.httpBaseUrl),
           failureReason,
           traceId,
         });
@@ -527,7 +664,7 @@ const make = Effect.gen(function* () {
         };
       }
       const decoded = responseOption.value.response;
-      const verified = yield* verifyEnvironmentHealthResponse({
+      const invalidResponse = yield* verifyEnvironmentHealthResponse({
         response: decoded,
         environmentId: input.environmentId,
         requestNonce: nonce,
@@ -536,10 +673,14 @@ const make = Effect.gen(function* () {
         relayIssuer,
         now: yield* DateTime.now,
       });
-      if (!verified) {
-        return yield* new EnvironmentMintResponseInvalid({
+      if (invalidResponse) {
+        return yield* EnvironmentMintResponseInvalid.fromEndpoint({
+          userId: input.userId,
           environmentId: input.environmentId,
           operation: "status",
+          httpBaseUrl: endpoint.httpBaseUrl,
+          reason: invalidResponse.reason,
+          ...(invalidResponse.cause !== undefined ? { cause: invalidResponse.cause } : {}),
         });
       }
       return {
@@ -586,13 +727,16 @@ const make = Effect.gen(function* () {
       const now = yield* DateTime.now;
       const expiresAt = DateTime.add(now, { minutes: 2 });
       const nonce = yield* crypto.randomUUIDv4.pipe(
-        Effect.mapError(
-          (cause) =>
-            new EnvironmentMintRequestFailed({
-              environmentId: input.environmentId,
-              operation: "connect",
-              cause,
-            }),
+        Effect.mapError((cause) =>
+          EnvironmentMintRequestFailed.fromEndpoint({
+            userId: input.userId,
+            environmentId: input.environmentId,
+            operation: "connect",
+            stage: "generate_nonce",
+            httpBaseUrl: endpoint.httpBaseUrl,
+            ...(input.deviceId ? { deviceId: input.deviceId } : {}),
+            cause,
+          }),
         ),
       );
       const payload = {
@@ -600,13 +744,16 @@ const make = Effect.gen(function* () {
         aud: `t3-env:${link.environmentId}`,
         sub: input.userId,
         jti: yield* crypto.randomUUIDv4.pipe(
-          Effect.mapError(
-            (cause) =>
-              new EnvironmentMintRequestFailed({
-                environmentId: input.environmentId,
-                operation: "connect",
-                cause,
-              }),
+          Effect.mapError((cause) =>
+            EnvironmentMintRequestFailed.fromEndpoint({
+              userId: input.userId,
+              environmentId: input.environmentId,
+              operation: "connect",
+              stage: "generate_request_id",
+              httpBaseUrl: endpoint.httpBaseUrl,
+              ...(input.deviceId ? { deviceId: input.deviceId } : {}),
+              cause,
+            }),
           ),
         ),
         iat: Math.floor(now.epochMilliseconds / 1_000),
@@ -623,13 +770,16 @@ const make = Effect.gen(function* () {
         typ: RELAY_MINT_REQUEST_TYP,
         payload,
       }).pipe(
-        Effect.mapError(
-          (cause) =>
-            new EnvironmentMintRequestFailed({
-              environmentId: input.environmentId,
-              operation: "connect",
-              cause,
-            }),
+        Effect.mapError((cause) =>
+          EnvironmentMintRequestFailed.fromEndpoint({
+            userId: input.userId,
+            environmentId: input.environmentId,
+            operation: "connect",
+            stage: "sign_proof",
+            httpBaseUrl: endpoint.httpBaseUrl,
+            ...(input.deviceId ? { deviceId: input.deviceId } : {}),
+            cause,
+          }),
         ),
       );
       const environmentClient = yield* makeEnvironmentClient(endpoint.httpBaseUrl);
@@ -637,21 +787,27 @@ const make = Effect.gen(function* () {
         .t3MintCredential({ payload: { proof } })
         .pipe(
           withoutRedirects,
-          Effect.mapError(
-            (cause) =>
-              new EnvironmentMintRequestFailed({
-                environmentId: input.environmentId,
-                operation: "connect",
-                cause,
-              }),
+          Effect.mapError((cause) =>
+            EnvironmentMintRequestFailed.fromEndpoint({
+              userId: input.userId,
+              environmentId: input.environmentId,
+              operation: "connect",
+              stage: "send_request",
+              httpBaseUrl: endpoint.httpBaseUrl,
+              ...(input.deviceId ? { deviceId: input.deviceId } : {}),
+              cause,
+            }),
           ),
           Effect.timeoutOption(Duration.millis(ENVIRONMENT_MINT_REQUEST_TIMEOUT_MS)),
           Effect.flatMap(
             Option.match({
               onNone: () =>
                 Effect.fail(
-                  new EnvironmentMintRequestTimedOut({
+                  EnvironmentMintRequestTimedOut.fromEndpoint({
+                    userId: input.userId,
                     environmentId: input.environmentId,
+                    httpBaseUrl: endpoint.httpBaseUrl,
+                    ...(input.deviceId ? { deviceId: input.deviceId } : {}),
                     timeoutMs: ENVIRONMENT_MINT_REQUEST_TIMEOUT_MS,
                   }),
                 ),
@@ -659,7 +815,7 @@ const make = Effect.gen(function* () {
             }),
           ),
         );
-      const verified = yield* verifyEnvironmentResponse({
+      const invalidResponse = yield* verifyEnvironmentResponse({
         response: decoded,
         environmentId: input.environmentId,
         requestNonce: nonce,
@@ -668,10 +824,15 @@ const make = Effect.gen(function* () {
         relayIssuer,
         nowEpochSeconds: Math.floor(now.epochMilliseconds / 1_000),
       });
-      if (!verified) {
-        return yield* new EnvironmentMintResponseInvalid({
+      if (invalidResponse) {
+        return yield* EnvironmentMintResponseInvalid.fromEndpoint({
+          userId: input.userId,
           environmentId: input.environmentId,
           operation: "connect",
+          httpBaseUrl: endpoint.httpBaseUrl,
+          ...(input.deviceId ? { deviceId: input.deviceId } : {}),
+          reason: invalidResponse.reason,
+          ...(invalidResponse.cause !== undefined ? { cause: invalidResponse.cause } : {}),
         });
       }
       return {
diff --git a/packages/client-runtime/src/authorization/remote.test.ts b/packages/client-runtime/src/authorization/remote.test.ts
index 6e6ccc86052..6db80e31233 100644
--- a/packages/client-runtime/src/authorization/remote.test.ts
+++ b/packages/client-runtime/src/authorization/remote.test.ts
@@ -391,7 +391,9 @@ describe("remote environment authorization", () => {
 
       expect(error).toBeInstanceOf(RemoteEnvironmentAuthTimeoutError);
       expect(error.message).toBe(
-        "Remote environment endpoint http://remote.example.com/.well-known/t3/environment timed out after 25ms.",
+        `Remote environment endpoint at host remote.example.com (${
+          "http://remote.example.com/.well-known/t3/environment".length
+        } URL characters) timed out after 25ms.`,
       );
     }).pipe(Effect.provide(TestClock.layer())),
   );
@@ -446,7 +448,9 @@ describe("remote environment authorization", () => {
 
       expect(error).toBeInstanceOf(RemoteEnvironmentAuthInvalidJsonError);
       expect(error.message).toBe(
-        "Remote environment endpoint returned an invalid response from https://remote.example.com/oauth/token.",
+        `Remote environment endpoint at host remote.example.com (${
+          "https://remote.example.com/oauth/token".length
+        } URL characters) returned an invalid response.`,
       );
     }),
   );
diff --git a/packages/client-runtime/src/authorization/remote.ts b/packages/client-runtime/src/authorization/remote.ts
index 69c157d0e50..4cfa6877ec7 100644
--- a/packages/client-runtime/src/authorization/remote.ts
+++ b/packages/client-runtime/src/authorization/remote.ts
@@ -15,6 +15,7 @@ import {
 } from "../rpc/http.ts";
 
 export {
+  isRemoteEnvironmentAuthUndeclaredStatusError,
   RemoteEnvironmentAuthFetchError,
   RemoteEnvironmentAuthInvalidJsonError,
   RemoteEnvironmentAuthTimeoutError,
diff --git a/packages/client-runtime/src/authorization/service.ts b/packages/client-runtime/src/authorization/service.ts
index 624ecf7f672..adcc7072d96 100644
--- a/packages/client-runtime/src/authorization/service.ts
+++ b/packages/client-runtime/src/authorization/service.ts
@@ -6,7 +6,7 @@ import {
   resolveRemoteDpopWebSocketConnectionUrl,
   resolveRemoteWebSocketConnectionUrl,
 } from "./remote.ts";
-import { environmentMismatchError, mapRemoteEnvironmentError } from "../connection/errors.ts";
+import { mapRemoteEnvironmentError } from "../connection/errors.ts";
 import { ConnectionBlockedError, type ConnectionAttemptError } from "../connection/model.ts";
 import { fetchRemoteEnvironmentDescriptor } from "../environment/descriptor.ts";
 import { environmentEndpointUrl } from "../environment/endpoint.ts";
@@ -112,9 +112,11 @@ export const make = Effect.gen(function* () {
         Effect.provideService(HttpClient.HttpClient, httpClient),
       );
       if (descriptor.environmentId !== input.expectedEnvironmentId) {
-        return yield* environmentMismatchError({
-          expected: input.expectedEnvironmentId,
-          actual: descriptor.environmentId,
+        return yield* new ConnectionBlockedError({
+          reason: "configuration",
+          detail: `Connected environment ${descriptor.environmentId} does not match ${input.expectedEnvironmentId}.`,
+          expectedEnvironmentId: input.expectedEnvironmentId,
+          actualEnvironmentId: descriptor.environmentId,
         });
       }
       const socketUrl = yield* resolveRemoteWebSocketConnectionUrl({
@@ -148,10 +150,11 @@ export const make = Effect.gen(function* () {
         })
         .pipe(
           Effect.mapError(
-            () =>
+            (cause) =>
               new ConnectionBlockedError({
                 reason: "configuration",
                 detail: "Could not create the websocket authorization proof.",
+                cause,
               }),
           ),
         );
@@ -175,10 +178,11 @@ export const make = Effect.gen(function* () {
     }) {
       const thumbprint = yield* signer.thumbprint.pipe(
         Effect.mapError(
-          () =>
+          (cause) =>
             new ConnectionBlockedError({
               reason: "configuration",
               detail: "Could not load the environment authorization key.",
+              cause,
             }),
         ),
         Effect.withSpan("environment.authorization.dpopKey.resolve"),
@@ -236,9 +240,11 @@ export const make = Effect.gen(function* () {
         Effect.withSpan("environment.authorization.descriptor"),
       );
       if (descriptor.environmentId !== input.expectedEnvironmentId) {
-        return yield* environmentMismatchError({
-          expected: input.expectedEnvironmentId,
-          actual: descriptor.environmentId,
+        return yield* new ConnectionBlockedError({
+          reason: "configuration",
+          detail: `Connected environment ${descriptor.environmentId} does not match ${input.expectedEnvironmentId}.`,
+          expectedEnvironmentId: input.expectedEnvironmentId,
+          actualEnvironmentId: descriptor.environmentId,
         });
       }
       const bootstrapProof = yield* signer
@@ -248,10 +254,11 @@ export const make = Effect.gen(function* () {
         })
         .pipe(
           Effect.mapError(
-            () =>
+            (cause) =>
               new ConnectionBlockedError({
                 reason: "configuration",
                 detail: "Could not create the environment authorization proof.",
+                cause,
               }),
           ),
         );
diff --git a/packages/client-runtime/src/connection/errors.test.ts b/packages/client-runtime/src/connection/errors.test.ts
new file mode 100644
index 00000000000..55b31edbc19
--- /dev/null
+++ b/packages/client-runtime/src/connection/errors.test.ts
@@ -0,0 +1,58 @@
+import { describe, expect, it } from "@effect/vitest";
+
+import { mapRemoteEnvironmentError } from "./errors.ts";
+import {
+  RemoteEnvironmentAuthFetchError,
+  RemoteEnvironmentAuthUndeclaredStatusError,
+} from "../rpc/http.ts";
+
+describe("connection error mapping", () => {
+  it("keeps transport diagnostics structured and redacted", () => {
+    const transportCause = new Error("sensitive transport implementation detail");
+    const requestUrl =
+      "https://environment-user:environment-password@environment.example.test/private/session?access_token=environment-secret#environment-fragment";
+    const source = RemoteEnvironmentAuthFetchError.fromRequestUrl(requestUrl, transportCause);
+
+    const error = mapRemoteEnvironmentError(source);
+
+    expect(source.message).toBe(
+      `Failed to fetch remote environment endpoint at host environment.example.test (${requestUrl.length} URL characters).`,
+    );
+    expect(source.message).not.toContain(transportCause.message);
+    expect(error).toMatchObject({
+      _tag: "ConnectionTransientError",
+      reason: "network",
+    });
+    expect(source).toMatchObject({
+      requestUrlInputLength: requestUrl.length,
+      requestUrlProtocol: "https:",
+      requestUrlHostname: "environment.example.test",
+    });
+    const diagnostics = JSON.stringify(source);
+    for (const secret of [
+      "environment-user",
+      "environment-password",
+      "/private/session",
+      "environment-secret",
+      "environment-fragment",
+    ]) {
+      expect(diagnostics).not.toContain(secret);
+      expect(source.message).not.toContain(secret);
+    }
+  });
+
+  it("keeps undeclared status diagnostics structured and redacted", () => {
+    const cause = new Error("upstream response metadata");
+    const requestUrl =
+      "https://environment-user:environment-password@environment.example.test/private/session?access_token=environment-secret#environment-fragment";
+    const error = RemoteEnvironmentAuthUndeclaredStatusError.fromRequestUrl(requestUrl, 502, cause);
+
+    expect(error).toMatchObject({
+      status: 502,
+      requestUrlInputLength: requestUrl.length,
+      requestUrlProtocol: "https:",
+      requestUrlHostname: "environment.example.test",
+    });
+    expect(error).not.toHaveProperty("requestUrl");
+  });
+});
diff --git a/packages/client-runtime/src/connection/errors.ts b/packages/client-runtime/src/connection/errors.ts
index f70e41adfe7..36a6fcc8fa8 100644
--- a/packages/client-runtime/src/connection/errors.ts
+++ b/packages/client-runtime/src/connection/errors.ts
@@ -1,6 +1,8 @@
-import type { EnvironmentId } from "@t3tools/contracts";
 import type { RelayProtectedError } from "@t3tools/contracts/relay";
-import type { ManagedRelayClientError } from "../relay/managedRelay.ts";
+import type {
+  ManagedRelayClientError,
+  ManagedRelayRequestFailedError,
+} from "../relay/managedRelay.ts";
 import type { RemoteEnvironmentAuthError } from "../authorization/remote.ts";
 import {
   ConnectionBlockedError,
@@ -8,31 +10,10 @@ import {
   ConnectionTransientError,
 } from "./model.ts";
 
-export function profileMissingError(connectionId: string): ConnectionBlockedError {
-  return new ConnectionBlockedError({
-    reason: "configuration",
-    detail: `Connection profile ${connectionId} is unavailable.`,
-  });
-}
-
-export function credentialMissingError(connectionId: string): ConnectionBlockedError {
-  return new ConnectionBlockedError({
-    reason: "authentication",
-    detail: `Connection credential ${connectionId} is unavailable.`,
-  });
-}
-
-export function environmentMismatchError(input: {
-  readonly expected: EnvironmentId;
-  readonly actual: EnvironmentId;
-}): ConnectionBlockedError {
-  return new ConnectionBlockedError({
-    reason: "configuration",
-    detail: `Connected environment ${input.actual} does not match ${input.expected}.`,
-  });
-}
-
-function relayProtectedError(error: RelayProtectedError): ConnectionAttemptError {
+function connectionErrorFromRelayProtectedError(
+  error: RelayProtectedError,
+  cause: ManagedRelayRequestFailedError,
+): ConnectionAttemptError {
   switch (error._tag) {
     case "RelayAuthInvalidError":
     case "RelayEnvironmentLinkProofExpiredError":
@@ -42,6 +23,7 @@ function relayProtectedError(error: RelayProtectedError): ConnectionAttemptError
         reason: "authentication",
         detail: error.message,
         traceId: error.traceId,
+        cause,
       });
     case "RelayEnvironmentConnectNotAuthorizedError":
     case "RelayEnvironmentLinkProofInvalidError":
@@ -49,12 +31,14 @@ function relayProtectedError(error: RelayProtectedError): ConnectionAttemptError
         reason: "permission",
         detail: error.message,
         traceId: error.traceId,
+        cause,
       });
     case "RelayEnvironmentEndpointTimedOutError":
       return new ConnectionTransientError({
         reason: "timeout",
         detail: error.message,
         traceId: error.traceId,
+        cause,
       });
     case "RelayEnvironmentEndpointUnavailableError":
     case "RelayEnvironmentLinkUnavailableError":
@@ -62,6 +46,7 @@ function relayProtectedError(error: RelayProtectedError): ConnectionAttemptError
         reason: "endpoint-unavailable",
         detail: error.message,
         traceId: error.traceId,
+        cause,
       });
     case "RelayEnvironmentLinkFailedError":
     case "RelayInternalError":
@@ -69,6 +54,7 @@ function relayProtectedError(error: RelayProtectedError): ConnectionAttemptError
         reason: "relay-unavailable",
         detail: error.message,
         traceId: error.traceId,
+        cause,
       });
   }
 }
@@ -77,27 +63,31 @@ export function mapManagedRelayError(error: ManagedRelayClientError): Connection
   switch (error._tag) {
     case "ManagedRelayRequestFailedError":
       if (error.relayError) {
-        return relayProtectedError(error.relayError);
+        return connectionErrorFromRelayProtectedError(error.relayError, error);
       }
       return new ConnectionTransientError({
         reason: "relay-unavailable",
         detail: error.message,
         ...(error.traceId ? { traceId: error.traceId } : {}),
+        cause: error,
       });
     case "ManagedRelayRequestTimeoutError":
       return new ConnectionTransientError({
         reason: "timeout",
         detail: error.message,
+        cause: error,
       });
     case "ManagedRelayUrlInvalidError":
       return new ConnectionBlockedError({
         reason: "configuration",
         detail: error.message,
+        cause: error,
       });
     case "ManagedRelayAccessTokenScopesUnexpectedError":
       return new ConnectionBlockedError({
         reason: "permission",
         detail: error.message,
+        cause: error,
       });
     case "ManagedRelayDpopKeyLoadError":
     case "ManagedRelayTokenProofCreationError":
@@ -105,6 +95,7 @@ export function mapManagedRelayError(error: ManagedRelayClientError): Connection
       return new ConnectionBlockedError({
         reason: "authentication",
         detail: error.message,
+        cause: error,
       });
   }
 }
@@ -118,6 +109,7 @@ export function mapRemoteEnvironmentError(
         reason: "authentication",
         detail: "The environment credential is invalid.",
         traceId: error.traceId,
+        cause: error,
       });
     case "EnvironmentScopeRequiredError":
     case "EnvironmentOperationForbiddenError":
@@ -125,34 +117,40 @@ export function mapRemoteEnvironmentError(
         reason: "permission",
         detail: "The environment credential does not grant the required access.",
         traceId: error.traceId,
+        cause: error,
       });
     case "EnvironmentRequestInvalidError":
       return new ConnectionBlockedError({
         reason: "configuration",
         detail: "The environment rejected the authentication request.",
         traceId: error.traceId,
+        cause: error,
       });
     case "RemoteEnvironmentAuthTimeoutError":
       return new ConnectionTransientError({
         reason: "timeout",
         detail: error.message,
+        cause: error,
       });
     case "RemoteEnvironmentAuthFetchError":
       return new ConnectionTransientError({
         reason: "network",
         detail: error.message,
+        cause: error,
       });
     case "EnvironmentInternalError":
       return new ConnectionTransientError({
         reason: "remote-unavailable",
         detail: "The environment could not authorize the connection.",
         traceId: error.traceId,
+        cause: error,
       });
     case "RemoteEnvironmentAuthInvalidJsonError":
     case "RemoteEnvironmentAuthUndeclaredStatusError":
       return new ConnectionTransientError({
         reason: "remote-unavailable",
         detail: error.message,
+        cause: error,
       });
   }
 }
diff --git a/packages/client-runtime/src/connection/model.test.ts b/packages/client-runtime/src/connection/model.test.ts
new file mode 100644
index 00000000000..0ca2363bce6
--- /dev/null
+++ b/packages/client-runtime/src/connection/model.test.ts
@@ -0,0 +1,41 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import {
+  ConnectionStorageOperationError,
+  ConnectionTransientError,
+  IndexedDbUnavailableError,
+} from "./model.ts";
+
+describe("ConnectionTransientError.fromStorageFailure", () => {
+  it("preserves structured operation context and the complete failure chain", () => {
+    const storageCause = new Error("quota exceeded");
+    const storageOperationCause = new ConnectionStorageOperationError({
+      operation: "write",
+      backend: "indexed-db",
+      storeName: "catalog",
+      cause: storageCause,
+    });
+
+    const error = ConnectionTransientError.fromStorageFailure(storageOperationCause);
+
+    expect(error).toMatchObject({
+      reason: "remote-unavailable",
+      cause: {
+        _tag: "ConnectionStorageOperationError",
+        operation: "write",
+        backend: "indexed-db",
+        storeName: "catalog",
+        cause: storageCause,
+      },
+    });
+    expect(error.detail).toBe("Could not write local connection data.");
+    expect(error.message).toBe("Connection attempt failed (remote-unavailable).");
+  });
+
+  it("maps a cause-free availability failure without inventing a defect", () => {
+    const error = ConnectionTransientError.fromStorageFailure(new IndexedDbUnavailableError());
+
+    expect(error.cause).toMatchObject({ _tag: "IndexedDbUnavailableError" });
+    expect((error.cause as IndexedDbUnavailableError).cause).toBeUndefined();
+  });
+});
diff --git a/packages/client-runtime/src/connection/model.ts b/packages/client-runtime/src/connection/model.ts
index fbcb302ed13..bba100cab58 100644
--- a/packages/client-runtime/src/connection/model.ts
+++ b/packages/client-runtime/src/connection/model.ts
@@ -75,16 +75,88 @@ export const ConnectionBlockedReason = Schema.Literals([
 ]);
 export type ConnectionBlockedReason = typeof ConnectionBlockedReason.Type;
 
+export const ConnectionStorageOperation = Schema.Literals([
+  "open",
+  "read",
+  "write",
+  "remove",
+  "load",
+  "save",
+  "delete",
+  "decode",
+  "encode",
+  "migrate",
+]);
+export type ConnectionStorageOperation = typeof ConnectionStorageOperation.Type;
+
+export const ConnectionStorageBackend = Schema.Literals([
+  "indexed-db",
+  "desktop-secure-storage",
+  "mobile-secure-storage",
+  "legacy-migration",
+  "schema",
+]);
+export type ConnectionStorageBackend = typeof ConnectionStorageBackend.Type;
+
+export class ConnectionStorageOperationError extends Schema.TaggedErrorClass<ConnectionStorageOperationError>()(
+  "ConnectionStorageOperationError",
+  {
+    operation: ConnectionStorageOperation,
+    backend: ConnectionStorageBackend,
+    storeName: Schema.optionalKey(Schema.String),
+    key: Schema.optionalKey(Schema.Unknown),
+    cause: Schema.Defect(),
+  },
+) {
+  override get message(): string {
+    return `Could not ${this.operation} local connection data.`;
+  }
+}
+
+export class IndexedDbUnavailableError extends Schema.TaggedErrorClass<IndexedDbUnavailableError>()(
+  "IndexedDbUnavailableError",
+  {},
+) {
+  override get message(): string {
+    return "IndexedDB is unavailable in this browser context.";
+  }
+}
+
+export class DesktopSecureStorageUnavailableError extends Schema.TaggedErrorClass<DesktopSecureStorageUnavailableError>()(
+  "DesktopSecureStorageUnavailableError",
+  {},
+) {
+  override get message(): string {
+    return "Desktop secure storage is unavailable in this system context.";
+  }
+}
+
+export const ConnectionStorageFailure = Schema.Union([
+  ConnectionStorageOperationError,
+  IndexedDbUnavailableError,
+  DesktopSecureStorageUnavailableError,
+]);
+export type ConnectionStorageFailure = typeof ConnectionStorageFailure.Type;
+
 export class ConnectionTransientError extends Schema.TaggedErrorClass<ConnectionTransientError>()(
   "ConnectionTransientError",
   {
     reason: ConnectionTransientReason,
     detail: Schema.String,
     traceId: Schema.optionalKey(Schema.String),
+    cause: Schema.optional(Schema.Defect()),
   },
 ) {
+  static fromStorageFailure(cause: ConnectionStorageFailure): ConnectionTransientError {
+    return new ConnectionTransientError({
+      reason: "remote-unavailable",
+      detail: cause.message,
+      cause,
+    });
+  }
+
   override get message(): string {
-    return this.detail;
+    return `Connection attempt failed (${this.reason}).`;
   }
 }
 
@@ -93,11 +165,15 @@ export class ConnectionBlockedError extends Schema.TaggedErrorClass<ConnectionBl
   {
     reason: ConnectionBlockedReason,
     detail: Schema.String,
+    connectionId: Schema.optionalKey(Schema.String),
+    expectedEnvironmentId: Schema.optionalKey(EnvironmentId),
+    actualEnvironmentId: Schema.optionalKey(EnvironmentId),
     traceId: Schema.optionalKey(Schema.String),
+    cause: Schema.optional(Schema.Defect()),
   },
 ) {
   override get message(): string {
-    return this.detail;
+    return `Connection attempt blocked (${this.reason}).`;
   }
 }
 
diff --git a/packages/client-runtime/src/connection/onboarding.test.ts b/packages/client-runtime/src/connection/onboarding.test.ts
index 9bee0dad6fb..2bdd57dbea0 100644
--- a/packages/client-runtime/src/connection/onboarding.test.ts
+++ b/packages/client-runtime/src/connection/onboarding.test.ts
@@ -155,7 +155,10 @@ describe("connection onboarding", () => {
       expect(error).toMatchObject({
         _tag: "ConnectionBlockedError",
         reason: "configuration",
-        message: "Enter a backend URL.",
+        message: "The pairing details are invalid.",
+        cause: expect.objectContaining({
+          message: "Enter a backend URL.",
+        }),
       });
       expect(calls).toEqual([]);
     }),
diff --git a/packages/client-runtime/src/connection/onboarding.ts b/packages/client-runtime/src/connection/onboarding.ts
index e76bcd50a2c..39db24a8a1b 100644
--- a/packages/client-runtime/src/connection/onboarding.ts
+++ b/packages/client-runtime/src/connection/onboarding.ts
@@ -77,7 +77,8 @@ const resolvePairingTarget = Effect.fn("clientRuntime.connection.onboarding.reso
       catch: (cause) =>
         new ConnectionBlockedError({
           reason: "configuration",
-          detail: cause instanceof Error ? cause.message : "The pairing details are invalid.",
+          detail: "The pairing details are invalid.",
+          cause,
         }),
     });
   },
@@ -189,7 +190,8 @@ export const prepareBearerConnectionUpdate = Effect.fn(
     catch: (cause) =>
       new ConnectionBlockedError({
         reason: "configuration",
-        detail: cause instanceof Error ? cause.message : "The environment URL is invalid.",
+        detail: "The environment URL is invalid.",
+        cause,
       }),
   });
   const connectionId = entry.target.connectionId;
diff --git a/packages/client-runtime/src/connection/presentation.ts b/packages/client-runtime/src/connection/presentation.ts
index ec7687dfe42..9f6e91f4b3e 100644
--- a/packages/client-runtime/src/connection/presentation.ts
+++ b/packages/client-runtime/src/connection/presentation.ts
@@ -35,7 +35,7 @@ export function presentConnectionState(
     case "connecting":
       return {
         phase: state.attempt <= 1 && state.lastFailure === null ? "connecting" : "reconnecting",
-        error: state.lastFailure?.message ?? null,
+        error: state.lastFailure?.detail ?? null,
         traceId: state.lastFailure?.traceId ?? null,
       };
     case "connected":
@@ -43,13 +43,13 @@ export function presentConnectionState(
     case "backoff":
       return {
         phase: "reconnecting",
-        error: state.lastFailure?.message ?? null,
+        error: state.lastFailure?.detail ?? null,
         traceId: state.lastFailure?.traceId ?? null,
       };
     case "blocked":
       return {
         phase: "error",
-        error: state.lastFailure?.message ?? null,
+        error: state.lastFailure?.detail ?? null,
         traceId: state.lastFailure?.traceId ?? null,
       };
   }
diff --git a/packages/client-runtime/src/connection/registry.test.ts b/packages/client-runtime/src/connection/registry.test.ts
index 885ba4cb781..0882aad801b 100644
--- a/packages/client-runtime/src/connection/registry.test.ts
+++ b/packages/client-runtime/src/connection/registry.test.ts
@@ -694,7 +694,10 @@ describe("EnvironmentRegistry", () => {
           Effect.fail(
             new Persistence.ConnectionPersistenceError({
               operation: "remove-connection",
-              message: "Storage is unavailable.",
+              stage: "write",
+              resource: "connection-catalog",
+              environmentId: RELAY_TARGET.environmentId,
+              cause: new Error("Storage is unavailable."),
             }),
           ),
       });
diff --git a/packages/client-runtime/src/connection/registry.ts b/packages/client-runtime/src/connection/registry.ts
index 3a95185d835..4d277294766 100644
--- a/packages/client-runtime/src/connection/registry.ts
+++ b/packages/client-runtime/src/connection/registry.ts
@@ -345,7 +345,9 @@ export const make = Effect.gen(function* () {
       persistedTargets,
       (target) =>
         acquireSupervisor(target.environmentId).pipe(
-          Effect.catchTag("EnvironmentNotRegisteredError", () => Effect.void),
+          Effect.catchTags({
+            EnvironmentNotRegisteredError: () => Effect.void,
+          }),
         ),
       {
         concurrency: "unbounded",
@@ -516,7 +518,9 @@ export const make = Effect.gen(function* () {
         relayEnvironmentIds,
         (environmentId) =>
           remove(environmentId).pipe(
-            Effect.catchTag("EnvironmentNotRegisteredError", () => Effect.void),
+            Effect.catchTags({
+              EnvironmentNotRegisteredError: () => Effect.void,
+            }),
           ),
         {
           concurrency: "unbounded",
@@ -529,7 +533,9 @@ export const make = Effect.gen(function* () {
   const retryNow = (environmentId: EnvironmentId) =>
     acquireSupervisor(environmentId).pipe(
       Effect.flatMap((supervisor) => supervisor.retryNow),
-      Effect.catchTag("EnvironmentNotRegisteredError", () => Effect.void),
+      Effect.catchTags({
+        EnvironmentNotRegisteredError: () => Effect.void,
+      }),
       Effect.withSpan("EnvironmentRegistry.retryNow"),
     );
   const state = Effect.fn("EnvironmentRegistry.state")(function* (environmentId: EnvironmentId) {
diff --git a/packages/client-runtime/src/connection/resolver.test.ts b/packages/client-runtime/src/connection/resolver.test.ts
index 0469e459d16..3e7dbc17dd8 100644
--- a/packages/client-runtime/src/connection/resolver.test.ts
+++ b/packages/client-runtime/src/connection/resolver.test.ts
@@ -23,6 +23,7 @@ import {
 import * as ConnectionCredentialStore from "./credentialStore.ts";
 import {
   BearerConnectionTarget,
+  ConnectionBlockedError,
   ConnectionTransientError,
   PrimaryConnectionTarget,
   RelayConnectionTarget,
@@ -437,6 +438,62 @@ describe("ConnectionResolver", () => {
     }),
   );
 
+  it.effect("retains the connection id when a bearer credential is unavailable", () =>
+    Effect.gen(function* () {
+      const target = new BearerConnectionTarget({
+        environmentId: ENVIRONMENT_ID,
+        label: "Saved",
+        connectionId: "saved-1",
+      });
+      const profile = new BearerConnectionProfile({
+        connectionId: "saved-1",
+        environmentId: ENVIRONMENT_ID,
+        label: "Saved",
+        httpBaseUrl: ENDPOINT.httpBaseUrl,
+        wsBaseUrl: ENDPOINT.wsBaseUrl,
+      });
+      const brokerLayer = yield* makeDependencies();
+      const broker = yield* ConnectionResolver.ConnectionResolver.pipe(Effect.provide(brokerLayer));
+
+      const error = yield* Effect.flip(broker.prepare(catalogEntry(target, Option.some(profile))));
+
+      expect(error).toBeInstanceOf(ConnectionBlockedError);
+      expect(error).toMatchObject({
+        reason: "authentication",
+        connectionId: "saved-1",
+      });
+    }),
+  );
+
+  it.effect("retains both environment ids when a connection profile does not match", () =>
+    Effect.gen(function* () {
+      const actualEnvironmentId = EnvironmentId.make("environment-2");
+      const target = new BearerConnectionTarget({
+        environmentId: ENVIRONMENT_ID,
+        label: "Saved",
+        connectionId: "saved-1",
+      });
+      const profile = new BearerConnectionProfile({
+        connectionId: "saved-1",
+        environmentId: actualEnvironmentId,
+        label: "Saved",
+        httpBaseUrl: ENDPOINT.httpBaseUrl,
+        wsBaseUrl: ENDPOINT.wsBaseUrl,
+      });
+      const brokerLayer = yield* makeDependencies();
+      const broker = yield* ConnectionResolver.ConnectionResolver.pipe(Effect.provide(brokerLayer));
+
+      const error = yield* Effect.flip(broker.prepare(catalogEntry(target, Option.some(profile))));
+
+      expect(error).toBeInstanceOf(ConnectionBlockedError);
+      expect(error).toMatchObject({
+        reason: "configuration",
+        expectedEnvironmentId: ENVIRONMENT_ID,
+        actualEnvironmentId,
+      });
+    }),
+  );
+
   it.effect("classifies relay request timeouts as retryable connection failures", () =>
     Effect.gen(function* () {
       const target = new RelayConnectionTarget({
diff --git a/packages/client-runtime/src/connection/resolver.ts b/packages/client-runtime/src/connection/resolver.ts
index c219bde092c..80357e7be12 100644
--- a/packages/client-runtime/src/connection/resolver.ts
+++ b/packages/client-runtime/src/connection/resolver.ts
@@ -16,12 +16,7 @@ import {
   SshConnectionProfile,
 } from "./catalog.ts";
 import * as ConnectionCredentialStore from "./credentialStore.ts";
-import {
-  credentialMissingError,
-  environmentMismatchError,
-  mapManagedRelayError,
-  profileMissingError,
-} from "./errors.ts";
+import { mapManagedRelayError } from "./errors.ts";
 import type {
   BearerConnectionTarget,
   ConnectionTarget,
@@ -95,7 +90,14 @@ const makeBearerBroker = Effect.fn("clientRuntime.connection.broker.makeBearer")
   ) {
     const target = entry.target;
     const profile = yield* Option.match(entry.profile, {
-      onNone: () => Effect.fail(profileMissingError(target.connectionId)),
+      onNone: () =>
+        Effect.fail(
+          new ConnectionBlockedError({
+            reason: "configuration",
+            detail: `Connection profile ${target.connectionId} is unavailable.`,
+            connectionId: target.connectionId,
+          }),
+        ),
       onSome: Effect.succeed,
     });
     if (!isBearerProfile(profile)) {
@@ -105,21 +107,34 @@ const makeBearerBroker = Effect.fn("clientRuntime.connection.broker.makeBearer")
       });
     }
     if (profile.environmentId !== target.environmentId) {
-      return yield* environmentMismatchError({
-        expected: target.environmentId,
-        actual: profile.environmentId,
+      return yield* new ConnectionBlockedError({
+        reason: "configuration",
+        detail: `Connected environment ${profile.environmentId} does not match ${target.environmentId}.`,
+        expectedEnvironmentId: target.environmentId,
+        actualEnvironmentId: profile.environmentId,
       });
     }
     const credential = yield* credentials.get(target.connectionId).pipe(
       Effect.flatMap(
         Option.match({
-          onNone: () => Effect.fail(credentialMissingError(target.connectionId)),
+          onNone: () =>
+            Effect.fail(
+              new ConnectionBlockedError({
+                reason: "authentication",
+                detail: `Connection credential ${target.connectionId} is unavailable.`,
+                connectionId: target.connectionId,
+              }),
+            ),
           onSome: Effect.succeed,
         }),
       ),
     );
     if (!isBearerCredential(credential)) {
-      return yield* credentialMissingError(target.connectionId);
+      return yield* new ConnectionBlockedError({
+        reason: "authentication",
+        detail: `Connection credential ${target.connectionId} is unavailable.`,
+        connectionId: target.connectionId,
+      });
     }
     const authorized = yield* remote.authorizeBearer({
       expectedEnvironmentId: target.environmentId,
@@ -164,9 +179,11 @@ const makeRelayBroker = Effect.fn("clientRuntime.connection.broker.makeRelay")(f
             })
             .pipe(Effect.mapError(mapManagedRelayError));
           if (connected.environmentId !== target.environmentId) {
-            return yield* environmentMismatchError({
-              expected: target.environmentId,
-              actual: connected.environmentId,
+            return yield* new ConnectionBlockedError({
+              reason: "configuration",
+              detail: `Connected environment ${connected.environmentId} does not match ${target.environmentId}.`,
+              expectedEnvironmentId: target.environmentId,
+              actualEnvironmentId: connected.environmentId,
             });
           }
           return connected;
@@ -196,7 +213,14 @@ const makeSshBroker = Effect.fn("clientRuntime.connection.broker.makeSsh")(funct
   ) {
     const target = entry.target;
     const profile = yield* Option.match(entry.profile, {
-      onNone: () => Effect.fail(profileMissingError(target.connectionId)),
+      onNone: () =>
+        Effect.fail(
+          new ConnectionBlockedError({
+            reason: "configuration",
+            detail: `Connection profile ${target.connectionId} is unavailable.`,
+            connectionId: target.connectionId,
+          }),
+        ),
       onSome: Effect.succeed,
     });
     if (!isSshProfile(profile)) {
@@ -206,9 +230,11 @@ const makeSshBroker = Effect.fn("clientRuntime.connection.broker.makeSsh")(funct
       });
     }
     if (profile.environmentId !== target.environmentId) {
-      return yield* environmentMismatchError({
-        expected: target.environmentId,
-        actual: profile.environmentId,
+      return yield* new ConnectionBlockedError({
+        reason: "configuration",
+        detail: `Connected environment ${profile.environmentId} does not match ${target.environmentId}.`,
+        expectedEnvironmentId: target.environmentId,
+        actualEnvironmentId: profile.environmentId,
       });
     }
     const prepared = yield* ssh.prepare({
diff --git a/packages/client-runtime/src/connection/supervisor.ts b/packages/client-runtime/src/connection/supervisor.ts
index d9efcd4263a..06883b97fd1 100644
--- a/packages/client-runtime/src/connection/supervisor.ts
+++ b/packages/client-runtime/src/connection/supervisor.ts
@@ -187,6 +187,7 @@ function failureFromExit<A>(
       error: new ConnectionTransientError({
         reason: "transport",
         detail: `${target.label} connection failed unexpectedly.`,
+        cause: exit.cause,
       }),
       attemptSpan: Option.none(),
     },
diff --git a/packages/client-runtime/src/platform/persistence.test.ts b/packages/client-runtime/src/platform/persistence.test.ts
new file mode 100644
index 00000000000..1485eab1f38
--- /dev/null
+++ b/packages/client-runtime/src/platform/persistence.test.ts
@@ -0,0 +1,76 @@
+import { EnvironmentId, ThreadId } from "@t3tools/contracts";
+import { describe, expect, it } from "@effect/vitest";
+
+import {
+  ConnectionStorageOperationError,
+  ConnectionTransientError,
+  DesktopSecureStorageUnavailableError,
+} from "../connection/model.ts";
+import { ConnectionPersistenceError } from "./persistence.ts";
+
+describe("ConnectionPersistenceError", () => {
+  it("retains storage context and cause without deriving its message from the cause", () => {
+    const cause = new Error("sensitive filesystem detail");
+    const error = new ConnectionPersistenceError({
+      operation: "load-thread",
+      stage: "decode",
+      resource: "thread-cache",
+      environmentId: EnvironmentId.make("environment-1"),
+      threadId: ThreadId.make("thread-1"),
+      cause,
+    });
+
+    expect(error.cause).toBe(cause);
+    expect(error.message).toBe(
+      "Could not load thread: thread cache decode failed for environment environment-1 and thread thread-1.",
+    );
+    expect(error.message).not.toContain(cause.message);
+  });
+
+  it.each([
+    ["decode", "read", "decode"],
+    ["encode", "write", "encode"],
+    ["migrate", "read", "migrate"],
+    ["remove", "write", "remove"],
+  ] as const)(
+    "derives the %s catalog stage from the structured storage failure",
+    (storageOperation, fallbackStage, expectedStage) => {
+      const cause = ConnectionTransientError.fromStorageFailure(
+        new ConnectionStorageOperationError({
+          operation: storageOperation,
+          backend: "schema",
+          cause: new Error("storage failure"),
+        }),
+      );
+
+      const error = ConnectionPersistenceError.fromStorageFailure({
+        operation: "register-connection",
+        fallbackStage,
+        resource: "connection-catalog",
+        environmentId: EnvironmentId.make("environment-1"),
+        cause,
+      });
+
+      expect(error.stage).toBe(expectedStage);
+      expect(error.message).toBe(
+        `Could not register connection: connection catalog ${expectedStage} failed for environment environment-1.`,
+      );
+      expect(error.cause).toBe(cause);
+    },
+  );
+
+  it("uses the caller's stage when a storage failure has no operation", () => {
+    const cause = ConnectionTransientError.fromStorageFailure(
+      new DesktopSecureStorageUnavailableError(),
+    );
+
+    const error = ConnectionPersistenceError.fromStorageFailure({
+      operation: "list-targets",
+      fallbackStage: "read",
+      resource: "connection-catalog",
+      cause,
+    });
+
+    expect(error.stage).toBe("read");
+  });
+});
diff --git a/packages/client-runtime/src/platform/persistence.ts b/packages/client-runtime/src/platform/persistence.ts
index 71664bf4601..3f4ce292baf 100644
--- a/packages/client-runtime/src/platform/persistence.ts
+++ b/packages/client-runtime/src/platform/persistence.ts
@@ -1,8 +1,8 @@
 import {
-  type EnvironmentId,
+  EnvironmentId,
   type OrchestrationThread,
   type OrchestrationShellSnapshot,
-  type ThreadId,
+  ThreadId,
 } from "@t3tools/contracts";
 import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
@@ -10,7 +10,14 @@ import * as Option from "effect/Option";
 import * as Schema from "effect/Schema";
 
 import type { ConnectionRegistration } from "../connection/catalog.ts";
-import type { ConnectionTarget } from "../connection/model.ts";
+import {
+  type ConnectionStorageOperation,
+  ConnectionStorageOperationError,
+  type ConnectionTarget,
+  type ConnectionTransientError,
+} from "../connection/model.ts";
+
+const isConnectionStorageOperationError = Schema.is(ConnectionStorageOperationError);
 
 export class ConnectionPersistenceError extends Schema.TaggedErrorClass<ConnectionPersistenceError>()(
   "ConnectionPersistenceError",
@@ -26,9 +33,79 @@ export class ConnectionPersistenceError extends Schema.TaggedErrorClass<Connecti
       "remove-thread",
       "clear-environment",
     ]),
-    message: Schema.String,
+    stage: Schema.Literals([
+      "resolve",
+      "read",
+      "parse",
+      "decode",
+      "encode",
+      "migrate",
+      "write",
+      "remove",
+    ]),
+    resource: Schema.Literals([
+      "connection-catalog",
+      "shell-cache",
+      "legacy-shell-cache",
+      "thread-cache",
+    ]),
+    environmentId: Schema.optionalKey(EnvironmentId),
+    threadId: Schema.optionalKey(ThreadId),
+    cause: Schema.Defect(),
   },
-) {}
+) {
+  static fromStorageFailure(input: {
+    readonly operation: ConnectionPersistenceError["operation"];
+    readonly fallbackStage: ConnectionPersistenceError["stage"];
+    readonly resource: ConnectionPersistenceError["resource"];
+    readonly environmentId?: EnvironmentId;
+    readonly threadId?: ThreadId;
+    readonly cause: ConnectionTransientError;
+  }) {
+    const { cause, fallbackStage, ...attributes } = input;
+    const storageCause = cause.cause;
+    const stage = isConnectionStorageOperationError(storageCause)
+      ? ConnectionPersistenceError.storageOperationStage(storageCause.operation)
+      : fallbackStage;
+
+    return new ConnectionPersistenceError({
+      ...attributes,
+      stage,
+      cause,
+    });
+  }
+
+  private static storageOperationStage(
+    operation: ConnectionStorageOperation,
+  ): ConnectionPersistenceError["stage"] {
+    switch (operation) {
+      case "open":
+        return "resolve";
+      case "read":
+      case "load":
+        return "read";
+      case "decode":
+        return "decode";
+      case "encode":
+        return "encode";
+      case "migrate":
+        return "migrate";
+      case "write":
+      case "save":
+        return "write";
+      case "delete":
+      case "remove":
+        return "remove";
+    }
+  }
+
+  override get message(): string {
+    const environment =
+      this.environmentId === undefined ? "" : ` for environment ${this.environmentId}`;
+    const thread = this.threadId === undefined ? "" : ` and thread ${this.threadId}`;
+    return `Could not ${this.operation.replaceAll("-", " ")}: ${this.resource.replaceAll("-", " ")} ${this.stage} failed${environment}${thread}.`;
+  }
+}
 
 export class ConnectionTargetStore extends Context.Service<
   ConnectionTargetStore,
diff --git a/packages/client-runtime/src/relay/discovery.test.ts b/packages/client-runtime/src/relay/discovery.test.ts
index 6bdc7798fb2..59ec0310873 100644
--- a/packages/client-runtime/src/relay/discovery.test.ts
+++ b/packages/client-runtime/src/relay/discovery.test.ts
@@ -8,6 +8,7 @@ import * as Deferred from "effect/Deferred";
 import * as Effect from "effect/Effect";
 import * as Fiber from "effect/Fiber";
 import * as Layer from "effect/Layer";
+import * as Logger from "effect/Logger";
 import * as Option from "effect/Option";
 import * as Ref from "effect/Ref";
 import * as Stream from "effect/Stream";
@@ -55,7 +56,9 @@ function status(
   };
 }
 
-const makeHarness = Effect.fn("RelayDiscoveryTest.makeHarness")(function* () {
+const makeHarness = Effect.fn("RelayDiscoveryTest.makeHarness")(function* (
+  testEnvironments: ReadonlyArray<RelayClientEnvironmentRecord> = environments,
+) {
   const networkStatus = yield* SubscriptionRef.make<NetworkStatus>("online");
   const listCalls = yield* Ref.make(0);
   const listFailure = yield* Ref.make<ManagedRelay.ManagedRelayClientError | null>(null);
@@ -74,7 +77,7 @@ const makeHarness = Effect.fn("RelayDiscoveryTest.makeHarness")(function* () {
       Deferred.Deferred<RelayEnvironmentStatusResponse, ManagedRelay.ManagedRelayClientError>
     >(),
   );
-  for (const environment of environments) {
+  for (const environment of testEnvironments) {
     const request = yield* Deferred.make<
       RelayEnvironmentStatusResponse,
       ManagedRelay.ManagedRelayClientError
@@ -98,7 +101,7 @@ const makeHarness = Effect.fn("RelayDiscoveryTest.makeHarness")(function* () {
         if (failure) {
           return yield* failure;
         }
-        return environments;
+        return testEnvironments;
       }),
     getEnvironmentStatus: ({ environmentId }) =>
       Ref.get(statusRequests).pipe(
@@ -170,6 +173,52 @@ const makeHarness = Effect.fn("RelayDiscoveryTest.makeHarness")(function* () {
 });
 
 describe("RelayEnvironmentDiscovery", () => {
+  it.effect("keeps managed endpoint secrets out of offline warnings", () => {
+    const httpBaseUrl =
+      "https://endpoint-user:endpoint-password@offline.example.test/private/workspace?access_token=endpoint-secret#endpoint-fragment";
+    const environment = {
+      ...environments[0]!,
+      endpoint: {
+        ...environments[0]!.endpoint,
+        httpBaseUrl,
+      },
+    } satisfies RelayClientEnvironmentRecord;
+    const capturedLogs: Array<ReadonlyArray<unknown>> = [];
+    const logger = Logger.make(({ message }) => {
+      capturedLogs.push(Array.isArray(message) ? message : [message]);
+    });
+
+    return Effect.gen(function* () {
+      const harness = yield* makeHarness([environment]);
+      yield* Effect.gen(function* () {
+        const discovery = yield* RelayEnvironmentDiscovery.RelayEnvironmentDiscovery;
+        const refreshFiber = yield* Effect.forkChild(discovery.refresh);
+        const requests = yield* Ref.get(harness.statusRequests);
+        yield* Deferred.succeed(
+          requests.get(environment.environmentId)!,
+          status(environment, "offline"),
+        );
+        yield* Fiber.join(refreshFiber);
+
+        expect(capturedLogs).toHaveLength(1);
+        const logFields = capturedLogs[0]?.find(
+          (value): value is Record<string, unknown> => typeof value === "object" && value !== null,
+        );
+        expect(logFields).toMatchObject({
+          environmentId: environment.environmentId,
+          endpointInputLength: httpBaseUrl.length,
+          endpointProtocol: "https:",
+          endpointHostname: "offline.example.test",
+        });
+        expect(logFields).not.toHaveProperty("endpoint");
+      }).pipe(
+        Effect.provide(
+          Layer.merge(harness.layer, Logger.layer([logger], { mergeWithExisting: false })),
+        ),
+      );
+    });
+  });
+
   it.effect("publishes each environment status as soon as that lookup completes", () =>
     Effect.gen(function* () {
       const harness = yield* makeHarness();
diff --git a/packages/client-runtime/src/relay/discovery.ts b/packages/client-runtime/src/relay/discovery.ts
index 8cbadea1ca5..1a6212a9bbc 100644
--- a/packages/client-runtime/src/relay/discovery.ts
+++ b/packages/client-runtime/src/relay/discovery.ts
@@ -3,6 +3,7 @@ import type {
   RelayEnvironmentStatusResponse,
 } from "@t3tools/contracts/relay";
 import { decodeRelayJwt } from "@t3tools/shared/relayJwt";
+import { getUrlDiagnostics } from "@t3tools/shared/urlDiagnostics";
 import {
   RelayEnvironmentConnectScope,
   RelayEnvironmentStatusScope,
@@ -63,6 +64,8 @@ function validateStatus(
       new ConnectionBlockedError({
         reason: "configuration",
         detail: "Relay returned status for a different environment.",
+        expectedEnvironmentId: environment.environmentId,
+        actualEnvironmentId: status.environmentId,
       }),
     );
   }
@@ -86,6 +89,8 @@ function validateStatus(
       new ConnectionBlockedError({
         reason: "configuration",
         detail: "Relay returned a descriptor for a different environment.",
+        expectedEnvironmentId: environment.environmentId,
+        actualEnvironmentId: status.descriptor.environmentId,
       }),
     );
   }
@@ -174,9 +179,16 @@ export const make = Effect.fn("RelayEnvironmentDiscovery.make")(function* () {
           return [true, new Map(current).set(environment.environmentId, fingerprint)];
         });
         if (shouldReport) {
+          const endpointDiagnostics = getUrlDiagnostics(result.success.endpoint.httpBaseUrl);
           yield* Effect.logWarning("Relay environment health check reported offline", {
             environmentId: result.success.environmentId,
-            endpoint: result.success.endpoint.httpBaseUrl,
+            endpointInputLength: endpointDiagnostics.inputLength,
+            ...(endpointDiagnostics.protocol === undefined
+              ? {}
+              : { endpointProtocol: endpointDiagnostics.protocol }),
+            ...(endpointDiagnostics.hostname === undefined
+              ? {}
+              : { endpointHostname: endpointDiagnostics.hostname }),
             message: result.success.error,
             traceId: result.success.traceId,
           });
diff --git a/packages/client-runtime/src/relay/managedRelay.test.ts b/packages/client-runtime/src/relay/managedRelay.test.ts
index 278c205883f..7d282754a3e 100644
--- a/packages/client-runtime/src/relay/managedRelay.test.ts
+++ b/packages/client-runtime/src/relay/managedRelay.test.ts
@@ -15,15 +15,15 @@ function managedRelayTestLayer(
   fetchFn: typeof globalThis.fetch,
   relayUrl = "https://relay.example.test",
   accessTokenStore?: ManagedRelay.ManagedRelayAccessTokenStore,
+  signer: ManagedRelay.ManagedRelayDpopSigner["Service"] = {
+    thumbprint: Effect.succeed("client-thumbprint"),
+    createProof: (input) => Effect.succeed(`proof:${input.url}`),
+  },
 ) {
   const httpClientLayer = remoteHttpClientLayer(fetchFn);
   const signerLayer = Layer.succeed(
     ManagedRelay.ManagedRelayDpopSigner,
-    ManagedRelay.ManagedRelayDpopSigner.of({
-      thumbprint: Effect.succeed("client-thumbprint"),
-      createProof: (input: ManagedRelay.ManagedRelayDpopProofInput) =>
-        Effect.succeed(`proof:${input.url}`),
-    }),
+    ManagedRelay.ManagedRelayDpopSigner.of(signer),
   );
   return ManagedRelay.layer({
     relayUrl,
@@ -39,6 +39,65 @@ function clerkToken(subject: string, nonce: string): string {
 }
 
 describe("ManagedRelayClient", () => {
+  it("redacts relay URLs and DPoP targets while preserving causes", () => {
+    const relayUrl =
+      "http://relay-user:relay-password@relay.example.test/private/workspace?access_token=relay-secret#relay-fragment";
+    const dpopTarget =
+      "https://dpop-user:dpop-password@relay.example.test/v1/client/dpop-token?access_token=dpop-secret#dpop-fragment";
+    const cause = new Error("proof failed");
+    const invalidUrlError = ManagedRelay.ManagedRelayUrlInvalidError.fromInput(relayUrl);
+    const proofErrors = [
+      ManagedRelay.ManagedRelayDpopKeyLoadError.fromTarget({
+        keyStore: "indexed-db",
+        method: "POST",
+        url: dpopTarget,
+        cause,
+      }),
+      ManagedRelay.ManagedRelayDpopProofCreationError.fromTarget({
+        method: "POST",
+        url: dpopTarget,
+        cause,
+      }),
+      ManagedRelay.ManagedRelayTokenProofCreationError.fromTarget({
+        method: "POST",
+        url: dpopTarget,
+        cause,
+      }),
+      ManagedRelay.ManagedRelayRequestProofCreationError.fromTarget({
+        method: "POST",
+        url: dpopTarget,
+        cause,
+      }),
+    ];
+
+    expect(invalidUrlError).toMatchObject({
+      relayUrlInputLength: relayUrl.length,
+      relayUrlProtocol: "http:",
+      relayUrlHostname: "relay.example.test",
+    });
+    const invalidUrlDiagnostics = JSON.stringify(invalidUrlError);
+    for (const secret of [
+      "relay-user",
+      "relay-password",
+      "/private/workspace",
+      "relay-secret",
+      "relay-fragment",
+    ]) {
+      expect(invalidUrlDiagnostics).not.toContain(secret);
+      expect(invalidUrlError.message).not.toContain(secret);
+    }
+
+    for (const error of proofErrors) {
+      expect(error.requestTarget).toBe("https://relay.example.test/v1/client/dpop-token");
+      expect(error.cause).toBe(cause);
+      const diagnostics = JSON.stringify(error);
+      for (const secret of ["dpop-user", "dpop-password", "dpop-secret", "dpop-fragment"]) {
+        expect(diagnostics).not.toContain(secret);
+        expect(error.message).not.toContain(secret);
+      }
+    }
+  });
+
   it.effect("owns tracing at service and implementation boundaries", () => {
     const spanNames: Array<string> = [];
     const tracer = Tracer.make({
@@ -124,13 +183,57 @@ describe("ManagedRelayClient", () => {
 
       expect(error).toMatchObject({
         _tag: "ManagedRelayUrlInvalidError",
-        relayUrl: "http://relay.example.test",
+        relayUrlInputLength: "http://relay.example.test".length,
+        relayUrlProtocol: "http:",
+        relayUrlHostname: "relay.example.test",
         message: "Relay URL must be a secure absolute HTTPS origin.",
       });
       expect(requestCount).toBe(0);
     }).pipe(Effect.provide(managedRelayTestLayer(fetchFn, "http://relay.example.test")));
   });
 
+  it.effect("preserves key-load failures when creating a token proof", () => {
+    const keyStoreCause = new Error("IndexedDB unavailable");
+    const fetchFn = (() => Promise.resolve(Response.json({}))) satisfies typeof globalThis.fetch;
+
+    return Effect.gen(function* () {
+      const relayClient = yield* ManagedRelay.ManagedRelayClient;
+      const error = yield* relayClient
+        .getEnvironmentStatus({
+          clerkToken: clerkToken("user-1", "session-1"),
+          scopes: [RelayEnvironmentStatusScope],
+          environmentId: EnvironmentId.make("env-1"),
+        })
+        .pipe(Effect.flip);
+
+      expect(error).toMatchObject({
+        _tag: "ManagedRelayTokenProofCreationError",
+        cause: {
+          _tag: "ManagedRelayDpopKeyLoadError",
+          keyStore: "indexed-db",
+          method: "POST",
+          message: "Could not load relay DPoP proof key.",
+          cause: keyStoreCause,
+        },
+      });
+    }).pipe(
+      Effect.provide(
+        managedRelayTestLayer(fetchFn, undefined, undefined, {
+          thumbprint: Effect.succeed("client-thumbprint"),
+          createProof: (input) =>
+            Effect.fail(
+              ManagedRelay.ManagedRelayDpopKeyLoadError.fromTarget({
+                keyStore: "indexed-db",
+                method: input.method,
+                url: input.url,
+                cause: keyStoreCause,
+              }),
+            ),
+        }),
+      ),
+    );
+  });
+
   it.effect("reuses usable DPoP tokens and refreshes cleared or expiring cache entries", () => {
     let tokenExchangeCount = 0;
     const fetchFn = ((input) => {
diff --git a/packages/client-runtime/src/relay/managedRelay.ts b/packages/client-runtime/src/relay/managedRelay.ts
index 08b720b46a3..fb4e6e4f0be 100644
--- a/packages/client-runtime/src/relay/managedRelay.ts
+++ b/packages/client-runtime/src/relay/managedRelay.ts
@@ -28,9 +28,11 @@ import {
   RelayUnregisterDeviceEndpoint,
 } from "@t3tools/contracts/relay";
 import { encodeOAuthScope, oauthScopeSetEquals } from "@t3tools/shared/oauthScope";
+import { redactDpopRequestTarget } from "@t3tools/shared/dpop";
 import { decodeRelayJwt } from "@t3tools/shared/relayJwt";
 import { withRelayClientTracing } from "@t3tools/shared/relayTracing";
 import { normalizeSecureRelayUrl } from "@t3tools/shared/relayUrl";
+import { getUrlDiagnostics } from "@t3tools/shared/urlDiagnostics";
 import * as Clock from "effect/Clock";
 import * as Context from "effect/Context";
 import * as Duration from "effect/Duration";
@@ -53,9 +55,25 @@ export class ManagedRelayDpopKeyLoadError extends Schema.TaggedErrorClass<Manage
   "ManagedRelayDpopKeyLoadError",
   {
     keyStore: Schema.Literals(["expo-secure-store", "indexed-db"]),
+    method: Schema.optional(Schema.String),
+    requestTarget: Schema.optional(Schema.String),
     cause: Schema.Defect(),
   },
 ) {
+  static fromTarget(input: {
+    readonly keyStore: "expo-secure-store" | "indexed-db";
+    readonly method: string;
+    readonly url: string;
+    readonly cause: unknown;
+  }): ManagedRelayDpopKeyLoadError {
+    return new ManagedRelayDpopKeyLoadError({
+      keyStore: input.keyStore,
+      method: input.method,
+      requestTarget: redactDpopRequestTarget(input.url),
+      cause: input.cause,
+    });
+  }
+
   override get message(): string {
     return "Could not load relay DPoP proof key.";
   }
@@ -65,12 +83,24 @@ export class ManagedRelayDpopProofCreationError extends Schema.TaggedErrorClass<
   "ManagedRelayDpopProofCreationError",
   {
     method: Schema.String,
-    url: Schema.String,
+    requestTarget: Schema.String,
     cause: Schema.Defect(),
   },
 ) {
+  static fromTarget(input: {
+    readonly method: string;
+    readonly url: string;
+    readonly cause: unknown;
+  }): ManagedRelayDpopProofCreationError {
+    return new ManagedRelayDpopProofCreationError({
+      method: input.method,
+      requestTarget: redactDpopRequestTarget(input.url),
+      cause: input.cause,
+    });
+  }
+
   override get message(): string {
-    return `Could not create the relay DPoP proof for ${this.method} ${this.url}.`;
+    return `Could not create the relay DPoP proof for ${this.method} ${this.requestTarget}.`;
   }
 }
 
@@ -125,14 +155,32 @@ export class ManagedRelayRequestTimeoutError extends Schema.TaggedErrorClass<Man
 export class ManagedRelayUrlInvalidError extends Schema.TaggedErrorClass<ManagedRelayUrlInvalidError>()(
   "ManagedRelayUrlInvalidError",
   {
-    relayUrl: Schema.String,
+    relayUrlInputLength: Schema.Number,
+    relayUrlProtocol: Schema.optionalKey(Schema.String),
+    relayUrlHostname: Schema.optionalKey(Schema.String),
   },
 ) {
+  static fromInput(relayUrl: string): ManagedRelayUrlInvalidError {
+    const diagnostics = getUrlDiagnostics(relayUrl);
+    return new ManagedRelayUrlInvalidError({
+      relayUrlInputLength: diagnostics.inputLength,
+      ...(diagnostics.protocol === undefined ? {} : { relayUrlProtocol: diagnostics.protocol }),
+      ...(diagnostics.hostname === undefined ? {} : { relayUrlHostname: diagnostics.hostname }),
+    });
+  }
+
   override get message(): string {
     return "Relay URL must be a secure absolute HTTPS origin.";
   }
 }
 
+type RelayHttpRequestError =
+  | RelayProtectedErrorType
+  | HttpClientError.HttpClientError
+  | Schema.SchemaError;
+
+const isRelayProtectedError = Schema.is(RelayProtectedError);
+
 export class ManagedRelayRequestFailedError extends Schema.TaggedErrorClass<ManagedRelayRequestFailedError>()(
   "ManagedRelayRequestFailedError",
   {
@@ -145,6 +193,15 @@ export class ManagedRelayRequestFailedError extends Schema.TaggedErrorClass<Mana
   override get message(): string {
     return `Could not ${this.action}.`;
   }
+
+  static fromHttpRequest(action: ManagedRelayRequestAction) {
+    return (cause: RelayHttpRequestError) =>
+      new ManagedRelayRequestFailedError({
+        action,
+        cause,
+        ...(isRelayProtectedError(cause) ? { relayError: cause, traceId: cause.traceId } : {}),
+      });
+  }
 }
 
 export class ManagedRelayAccessTokenScopesUnexpectedError extends Schema.TaggedErrorClass<ManagedRelayAccessTokenScopesUnexpectedError>()(
@@ -163,10 +220,22 @@ export class ManagedRelayTokenProofCreationError extends Schema.TaggedErrorClass
   "ManagedRelayTokenProofCreationError",
   {
     method: Schema.String,
-    url: Schema.String,
+    requestTarget: Schema.String,
     cause: Schema.Defect(),
   },
 ) {
+  static fromTarget(input: {
+    readonly method: string;
+    readonly url: string;
+    readonly cause: unknown;
+  }): ManagedRelayTokenProofCreationError {
+    return new ManagedRelayTokenProofCreationError({
+      method: input.method,
+      requestTarget: redactDpopRequestTarget(input.url),
+      cause: input.cause,
+    });
+  }
+
   override get message(): string {
     return "Could not create relay token DPoP proof.";
   }
@@ -176,10 +245,22 @@ export class ManagedRelayRequestProofCreationError extends Schema.TaggedErrorCla
   "ManagedRelayRequestProofCreationError",
   {
     method: Schema.String,
-    url: Schema.String,
+    requestTarget: Schema.String,
     cause: Schema.Defect(),
   },
 ) {
+  static fromTarget(input: {
+    readonly method: string;
+    readonly url: string;
+    readonly cause: unknown;
+  }): ManagedRelayRequestProofCreationError {
+    return new ManagedRelayRequestProofCreationError({
+      method: input.method,
+      requestTarget: redactDpopRequestTarget(input.url),
+      cause: input.cause,
+    });
+  }
+
   override get message(): string {
     return "Could not create relay request DPoP proof.";
   }
@@ -196,18 +277,13 @@ export const ManagedRelayClientError = Schema.Union([
 ]);
 export type ManagedRelayClientError = typeof ManagedRelayClientError.Type;
 
-type RelayHttpRequestError =
-  | RelayProtectedErrorType
-  | HttpClientError.HttpClientError
-  | Schema.SchemaError;
-
 export class ManagedRelayDpopSigner extends Context.Service<
   ManagedRelayDpopSigner,
   {
     readonly thumbprint: Effect.Effect<string, ManagedRelayDpopKeyLoadError>;
     readonly createProof: (
       input: ManagedRelayDpopProofInput,
-    ) => Effect.Effect<string, ManagedRelayDpopProofCreationError>;
+    ) => Effect.Effect<string, ManagedRelayDpopSignerError>;
   }
 >()("@t3tools/client-runtime/relay/managedRelay/ManagedRelayDpopSigner") {}
 
@@ -290,28 +366,8 @@ export class ManagedRelayClient extends Context.Service<
   }
 >()("@t3tools/client-runtime/relay/managedRelay/ManagedRelayClient") {}
 
-const isRelayProtectedError = Schema.is(RelayProtectedError);
-
-function relayRequestError(action: ManagedRelayRequestAction) {
-  return (cause: RelayHttpRequestError): ManagedRelayClientError =>
-    new ManagedRelayRequestFailedError({
-      action,
-      cause,
-      ...(isRelayProtectedError(cause) ? { relayError: cause, traceId: cause.traceId } : {}),
-    });
-}
-
-function proofCreationErrorFields(error: ManagedRelayDpopProofCreationError) {
-  return {
-    method: error.method,
-    url: error.url,
-    cause: error,
-  };
-}
-
-function isRejectedDpopAccessToken(error: ManagedRelayClientError): boolean {
+function isRejectedDpopAccessToken(error: ManagedRelayRequestFailedError): boolean {
   return (
-    error._tag === "ManagedRelayRequestFailedError" &&
     error.relayError?._tag === "RelayAuthInvalidError" &&
     error.relayError.reason === "invalid_bearer"
   );
@@ -383,7 +439,7 @@ function dpopHeaders(authorization: ManagedRelayAuthorization) {
 function disabledManagedRelayClient(relayUrl: string): ManagedRelayClient["Service"] {
   const unavailable = (spanName: string) =>
     Effect.fn(spanName)(function* () {
-      return yield* new ManagedRelayUrlInvalidError({ relayUrl });
+      return yield* ManagedRelayUrlInvalidError.fromInput(relayUrl);
     });
   return ManagedRelayClient.of({
     relayUrl,
@@ -461,13 +517,16 @@ export const make = Effect.fn("ManagedRelayClient.make")(function* (
         "relay.client_id": options.clientId,
         "relay.scopes": input.scopes.join(" "),
       });
-      const proof = yield* signer
-        .createProof(dpopProofTargets.exchangeAccessToken())
-        .pipe(
-          Effect.mapError(
-            (error) => new ManagedRelayTokenProofCreationError(proofCreationErrorFields(error)),
-          ),
-        );
+      const proofTarget = dpopProofTargets.exchangeAccessToken();
+      const proof = yield* signer.createProof(proofTarget).pipe(
+        Effect.mapError((cause) =>
+          ManagedRelayTokenProofCreationError.fromTarget({
+            method: proofTarget.method,
+            url: proofTarget.url,
+            cause,
+          }),
+        ),
+      );
       const response = yield* client.token
         .exchangeDpopAccessToken({
           headers: { dpop: proof },
@@ -482,7 +541,9 @@ export const make = Effect.fn("ManagedRelayClient.make")(function* (
           },
         })
         .pipe(
-          Effect.mapError(relayRequestError("exchange relay DPoP access token")),
+          Effect.mapError(
+            ManagedRelayRequestFailedError.fromHttpRequest("exchange relay DPoP access token"),
+          ),
           timeoutRelayRequest("Relay DPoP access token exchange"),
         );
       if (!oauthScopeSetEquals(response.scope, input.scopes)) {
@@ -574,7 +635,7 @@ export const make = Effect.fn("ManagedRelayClient.make")(function* (
       "relay.client_id": options.clientId,
       "relay.scopes": input.scopes.join(" "),
       "http.request.method": input.target.method,
-      "url.full": input.target.url,
+      "url.full": redactDpopRequestTarget(input.target.url),
     });
     const thumbprint = yield* signer.thumbprint;
     const token = yield* obtainAccessToken({
@@ -588,8 +649,12 @@ export const make = Effect.fn("ManagedRelayClient.make")(function* (
         accessToken: token.accessToken,
       })
       .pipe(
-        Effect.mapError(
-          (error) => new ManagedRelayRequestProofCreationError(proofCreationErrorFields(error)),
+        Effect.mapError((cause) =>
+          ManagedRelayRequestProofCreationError.fromTarget({
+            method: input.target.method,
+            url: input.target.url,
+            cause,
+          }),
         ),
       );
     return { accessToken: token.accessToken, proof, thumbprint };
@@ -623,27 +688,29 @@ export const make = Effect.fn("ManagedRelayClient.make")(function* (
       authorize(input).pipe(
         Effect.flatMap((authorization) =>
           request(authorization).pipe(
-            Effect.catch((error) => {
-              if (!isRejectedDpopAccessToken(error)) {
-                return Effect.fail(error);
-              }
-              return invalidateAccessToken(authorization.accessToken).pipe(
-                Effect.tap((invalidated) =>
-                  Effect.annotateCurrentSpan({
-                    "relay.token_cache.invalidated": invalidated,
-                    "relay.token_cache.invalidation_reason": "invalid_bearer",
-                    "relay.token_cache.retry_after_invalidation": refreshRejectedToken,
-                  }),
-                ),
-                Effect.tap((invalidated) =>
-                  invalidated && refreshRejectedToken
-                    ? Effect.logWarning(
-                        "Relay rejected a cached DPoP access token; refreshing it once.",
-                      )
-                    : Effect.void,
-                ),
-                Effect.andThen(refreshRejectedToken ? attempt(false) : Effect.fail(error)),
-              );
+            Effect.catchTags({
+              ManagedRelayRequestFailedError: (error) => {
+                if (!isRejectedDpopAccessToken(error)) {
+                  return Effect.fail(error);
+                }
+                return invalidateAccessToken(authorization.accessToken).pipe(
+                  Effect.tap((invalidated) =>
+                    Effect.annotateCurrentSpan({
+                      "relay.token_cache.invalidated": invalidated,
+                      "relay.token_cache.invalidation_reason": "invalid_bearer",
+                      "relay.token_cache.retry_after_invalidation": refreshRejectedToken,
+                    }),
+                  ),
+                  Effect.tap((invalidated) =>
+                    invalidated && refreshRejectedToken
+                      ? Effect.logWarning(
+                          "Relay rejected a cached DPoP access token; refreshing it once.",
+                        )
+                      : Effect.void,
+                  ),
+                  Effect.andThen(refreshRejectedToken ? attempt(false) : Effect.fail(error)),
+                );
+              },
             }),
           ),
         ),
@@ -676,7 +743,9 @@ export const make = Effect.fn("ManagedRelayClient.make")(function* (
           .listEnvironments({ headers: bearerHeaders(input.clerkToken) })
           .pipe(
             Effect.map((response) => response.environments),
-            Effect.mapError(relayRequestError("list relay-managed environments")),
+            Effect.mapError(
+              ManagedRelayRequestFailedError.fromHttpRequest("list relay-managed environments"),
+            ),
             timeoutRelayRequest("Relay environment listing"),
           );
       },
@@ -691,7 +760,9 @@ export const make = Effect.fn("ManagedRelayClient.make")(function* (
           })
           .pipe(
             Effect.map((response) => response.devices),
-            Effect.mapError(relayRequestError("list relay client devices")),
+            Effect.mapError(
+              ManagedRelayRequestFailedError.fromHttpRequest("list relay client devices"),
+            ),
             timeoutRelayRequest("Relay client device listing"),
           );
       },
@@ -706,7 +777,11 @@ export const make = Effect.fn("ManagedRelayClient.make")(function* (
             payload: input.payload,
           })
           .pipe(
-            Effect.mapError(relayRequestError("create relay environment link challenge")),
+            Effect.mapError(
+              ManagedRelayRequestFailedError.fromHttpRequest(
+                "create relay environment link challenge",
+              ),
+            ),
             timeoutRelayRequest("Relay environment link challenge"),
           );
       },
@@ -721,7 +796,9 @@ export const make = Effect.fn("ManagedRelayClient.make")(function* (
             payload: input.payload,
           })
           .pipe(
-            Effect.mapError(relayRequestError("link relay environment")),
+            Effect.mapError(
+              ManagedRelayRequestFailedError.fromHttpRequest("link relay environment"),
+            ),
             timeoutRelayRequest("Relay environment linking"),
           );
       },
@@ -736,7 +813,9 @@ export const make = Effect.fn("ManagedRelayClient.make")(function* (
             params: { environmentId: input.environmentId },
           })
           .pipe(
-            Effect.mapError(relayRequestError("unlink relay environment")),
+            Effect.mapError(
+              ManagedRelayRequestFailedError.fromHttpRequest("unlink relay environment"),
+            ),
             timeoutRelayRequest("Relay environment unlinking"),
           );
       },
@@ -761,7 +840,9 @@ export const make = Effect.fn("ManagedRelayClient.make")(function* (
                 params: { environmentId: input.environmentId },
               })
               .pipe(
-                Effect.mapError(relayRequestError("get relay environment status")),
+                Effect.mapError(
+                  ManagedRelayRequestFailedError.fromHttpRequest("get relay environment status"),
+                ),
                 timeoutRelayRequest("Relay environment status request"),
               ),
         );
@@ -792,7 +873,9 @@ export const make = Effect.fn("ManagedRelayClient.make")(function* (
                 payload,
               })
               .pipe(
-                Effect.mapError(relayRequestError("connect relay environment")),
+                Effect.mapError(
+                  ManagedRelayRequestFailedError.fromHttpRequest("connect relay environment"),
+                ),
                 timeoutRelayRequest("Relay environment connection"),
               );
           },
@@ -815,7 +898,9 @@ export const make = Effect.fn("ManagedRelayClient.make")(function* (
                 payload: input.payload,
               })
               .pipe(
-                Effect.mapError(relayRequestError("register relay mobile device")),
+                Effect.mapError(
+                  ManagedRelayRequestFailedError.fromHttpRequest("register relay mobile device"),
+                ),
                 timeoutRelayRequest("Relay mobile device registration"),
               ),
         );
@@ -837,7 +922,9 @@ export const make = Effect.fn("ManagedRelayClient.make")(function* (
                 params: { deviceId: input.deviceId },
               })
               .pipe(
-                Effect.mapError(relayRequestError("unregister relay mobile device")),
+                Effect.mapError(
+                  ManagedRelayRequestFailedError.fromHttpRequest("unregister relay mobile device"),
+                ),
                 timeoutRelayRequest("Relay mobile device unregistration"),
               ),
         );
@@ -859,7 +946,9 @@ export const make = Effect.fn("ManagedRelayClient.make")(function* (
                 payload: input.payload,
               })
               .pipe(
-                Effect.mapError(relayRequestError("register relay live activity")),
+                Effect.mapError(
+                  ManagedRelayRequestFailedError.fromHttpRequest("register relay live activity"),
+                ),
                 timeoutRelayRequest("Relay Live Activity registration"),
               ),
         );
diff --git a/packages/client-runtime/src/relay/managedRelayState.test.ts b/packages/client-runtime/src/relay/managedRelayState.test.ts
index 49400d32aef..0c0793d966d 100644
--- a/packages/client-runtime/src/relay/managedRelayState.test.ts
+++ b/packages/client-runtime/src/relay/managedRelayState.test.ts
@@ -5,6 +5,7 @@ import type {
   RelayEnvironmentStatusResponse,
 } from "@t3tools/contracts/relay";
 import { describe, expect, it } from "@effect/vitest";
+import * as Cause from "effect/Cause";
 import * as Effect from "effect/Effect";
 import * as Fiber from "effect/Fiber";
 import * as Layer from "effect/Layer";
@@ -17,6 +18,11 @@ import {
   createManagedRelayQueryManager,
   createManagedRelaySession,
   managedRelayAccountChanges,
+  ManagedRelaySessionUnavailableError,
+  ManagedRelayStatusEndpointMismatchError,
+  ManagedRelayStatusEnvironmentMismatchError,
+  ManagedRelayTokenReadError,
+  ManagedRelayTokenUnavailableError,
   type ManagedRelayQueryEvent,
   managedRelaySessionAtom,
   readManagedRelaySnapshotState,
@@ -109,6 +115,65 @@ function clerkToken(expiresAtSeconds: number): string {
 describe("createManagedRelayQueryManager", () => {
   afterEach(resetRegistry);
 
+  it("redacts endpoint mismatch secrets while retaining correlation fields", () => {
+    const expectedHttpBaseUrl =
+      "https://expected-user:expected-password@expected.example.test/private/catalog?token=expected-secret#expected-fragment";
+    const expectedWsBaseUrl =
+      "wss://expected-user:expected-password@expected.example.test/private/socket?token=expected-secret#expected-fragment";
+    const actualHttpBaseUrl =
+      "https://actual-user:actual-password@actual.example.test/private/catalog?token=actual-secret#actual-fragment";
+    const actualWsBaseUrl =
+      "wss://actual-user:actual-password@actual.example.test/private/socket?token=actual-secret#actual-fragment";
+
+    const error = ManagedRelayStatusEndpointMismatchError.fromEndpoints({
+      environmentId: environment.environmentId,
+      expectedEndpoint: {
+        providerKind: "cloudflare_tunnel",
+        httpBaseUrl: expectedHttpBaseUrl,
+        wsBaseUrl: expectedWsBaseUrl,
+      },
+      actualEndpoint: {
+        providerKind: "cloudflare_tunnel",
+        httpBaseUrl: actualHttpBaseUrl,
+        wsBaseUrl: actualWsBaseUrl,
+      },
+    });
+
+    expect(error).toMatchObject({
+      expectedProviderKind: "cloudflare_tunnel",
+      expectedHttpBaseUrlInputLength: expectedHttpBaseUrl.length,
+      expectedHttpBaseUrlProtocol: "https:",
+      expectedHttpBaseUrlHostname: "expected.example.test",
+      expectedWsBaseUrlInputLength: expectedWsBaseUrl.length,
+      expectedWsBaseUrlProtocol: "wss:",
+      expectedWsBaseUrlHostname: "expected.example.test",
+      actualProviderKind: "cloudflare_tunnel",
+      actualHttpBaseUrlInputLength: actualHttpBaseUrl.length,
+      actualHttpBaseUrlProtocol: "https:",
+      actualHttpBaseUrlHostname: "actual.example.test",
+      actualWsBaseUrlInputLength: actualWsBaseUrl.length,
+      actualWsBaseUrlProtocol: "wss:",
+      actualWsBaseUrlHostname: "actual.example.test",
+    });
+    expect(error).not.toHaveProperty("expectedEndpoint");
+    expect(error).not.toHaveProperty("actualEndpoint");
+    const exposedText = `${Object.values(error).join(" ")} ${error.message}`;
+    for (const secret of [
+      "expected-user",
+      "expected-password",
+      "/private/catalog",
+      "/private/socket",
+      "expected-secret",
+      "expected-fragment",
+      "actual-user",
+      "actual-password",
+      "actual-secret",
+      "actual-fragment",
+    ]) {
+      expect(exposedText).not.toContain(secret);
+    }
+  });
+
   it.effect("waits for the current cloud session before reading its token", () =>
     Effect.gen(function* () {
       const tokenFiber = yield* waitForManagedRelayClerkToken(registry).pipe(Effect.forkChild);
@@ -148,6 +213,62 @@ describe("createManagedRelayQueryManager", () => {
     }),
   );
 
+  it.effect("preserves token provider failure context", () =>
+    Effect.gen(function* () {
+      const cause = new Error("Clerk session failed");
+      const session = createManagedRelaySession({
+        accountId: "account-1",
+        readClerkToken: () => Promise.reject(cause),
+      });
+
+      const error = yield* Effect.flip(session.readClerkToken());
+
+      expect(error).toBeInstanceOf(ManagedRelayTokenReadError);
+      expect(error).toMatchObject({
+        _tag: "ManagedRelayTokenReadError",
+        accountId: "account-1",
+        cause,
+      });
+    }),
+  );
+
+  it.effect("distinguishes unavailable tokens from unavailable sessions", () =>
+    Effect.gen(function* () {
+      setManagedRelaySession(registry, {
+        accountId: "account-1",
+        readClerkToken: () => Promise.resolve(null),
+      });
+
+      const tokenError = yield* Effect.flip(waitForManagedRelayClerkToken(registry));
+      expect(tokenError).toBeInstanceOf(ManagedRelayTokenUnavailableError);
+      expect(tokenError).toMatchObject({
+        _tag: "ManagedRelayTokenUnavailableError",
+        accountId: "account-1",
+      });
+
+      setManagedRelaySession(registry, null);
+      const manager = createManager();
+      const atom = manager.environmentsAtom("account-1");
+      registry.get(atom);
+
+      yield* Effect.promise(() =>
+        vi.waitFor(() => {
+          const result = registry.get(atom);
+          expect(result._tag).toBe("Failure");
+          if (result._tag !== "Failure") {
+            return;
+          }
+          const error = Cause.squash(result.cause);
+          expect(error).toBeInstanceOf(ManagedRelaySessionUnavailableError);
+          expect(error).toMatchObject({
+            _tag: "ManagedRelaySessionUnavailableError",
+            requestedAccountId: "account-1",
+          });
+        }),
+      );
+    }),
+  );
+
   it.effect("updates the token provider without replacing a same-account session", () =>
     Effect.gen(function* () {
       const firstRead = vi.fn(() => Promise.resolve<string | null>(null));
@@ -197,30 +318,38 @@ describe("createManagedRelayQueryManager", () => {
     }),
   );
 
-  it("emits credential changes only when the managed relay account changes", async () => {
-    setManagedRelaySession(registry, {
-      accountId: "account-1",
-      readClerkToken: () => Promise.resolve("first-token"),
-    });
-    const changes = Effect.runPromise(
-      managedRelayAccountChanges(registry).pipe(Stream.take(2), Stream.runCollect),
-    );
-    await vi.waitFor(() => {
-      expect(registry.getNodes().get(managedRelaySessionAtom)?.listeners.size).toBeGreaterThan(0);
-    });
+  it.effect("emits credential changes only when the managed relay account changes", () =>
+    Effect.gen(function* () {
+      setManagedRelaySession(registry, {
+        accountId: "account-1",
+        readClerkToken: () => Promise.resolve("first-token"),
+      });
+      const changes = yield* managedRelayAccountChanges(registry).pipe(
+        Stream.take(2),
+        Stream.runCollect,
+        Effect.forkChild,
+      );
+      yield* Effect.promise(() =>
+        vi.waitFor(() => {
+          expect(registry.getNodes().get(managedRelaySessionAtom)?.listeners.size).toBeGreaterThan(
+            0,
+          );
+        }),
+      );
 
-    setManagedRelaySession(registry, {
-      accountId: "account-1",
-      readClerkToken: () => Promise.resolve("refreshed-token"),
-    });
-    setManagedRelaySession(registry, {
-      accountId: "account-2",
-      readClerkToken: () => Promise.resolve("second-token"),
-    });
-    setManagedRelaySession(registry, null);
+      setManagedRelaySession(registry, {
+        accountId: "account-1",
+        readClerkToken: () => Promise.resolve("refreshed-token"),
+      });
+      setManagedRelaySession(registry, {
+        accountId: "account-2",
+        readClerkToken: () => Promise.resolve("second-token"),
+      });
+      setManagedRelaySession(registry, null);
 
-    expect(Array.from(await changes)).toEqual(["account-2", null]);
-  });
+      expect(Array.from(yield* Fiber.join(changes))).toEqual(["account-2", null]);
+    }),
+  );
 
   it("shares one Clerk token read across concurrent relay list and status queries", async () => {
     const secondEnvironment = {
@@ -349,8 +478,20 @@ describe("createManagedRelayQueryManager", () => {
 
     registry.get(atom);
     await vi.waitFor(() => {
-      expect(readManagedRelaySnapshotState(registry.get(atom)).error).toBe(
-        "Relay returned status for a different environment.",
+      const result = registry.get(atom);
+      expect(result._tag).toBe("Failure");
+      if (result._tag !== "Failure") {
+        return;
+      }
+      const error = Cause.squash(result.cause);
+      expect(error).toBeInstanceOf(ManagedRelayStatusEnvironmentMismatchError);
+      expect(error).toMatchObject({
+        _tag: "ManagedRelayStatusEnvironmentMismatchError",
+        expectedEnvironmentId: environment.environmentId,
+        actualEnvironmentId: mismatchedStatus.environmentId,
+      });
+      expect(readManagedRelaySnapshotState(result).error).toBe(
+        "Relay returned status for environment environment-2 instead of environment-1.",
       );
     });
   });
diff --git a/packages/client-runtime/src/relay/managedRelayState.ts b/packages/client-runtime/src/relay/managedRelayState.ts
index ec6a0710dd1..b65dbff002a 100644
--- a/packages/client-runtime/src/relay/managedRelayState.ts
+++ b/packages/client-runtime/src/relay/managedRelayState.ts
@@ -2,16 +2,19 @@ import type {
   RelayClientEnvironmentRecord,
   RelayEnvironmentStatusResponse,
 } from "@t3tools/contracts/relay";
+import { EnvironmentId } from "@t3tools/contracts";
 import {
   RelayEnvironmentConnectScope,
   RelayEnvironmentStatusScope,
+  RelayManagedEndpointProviderKind,
 } from "@t3tools/contracts/relay";
 import { decodeRelayJwt } from "@t3tools/shared/relayJwt";
+import { getUrlDiagnostics } from "@t3tools/shared/urlDiagnostics";
 import * as Cause from "effect/Cause";
 import * as Clock from "effect/Clock";
-import * as Data from "effect/Data";
 import * as Effect from "effect/Effect";
 import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
 import * as Stream from "effect/Stream";
 import { AsyncResult, Atom, AtomRegistry } from "effect/unstable/reactivity";
 
@@ -55,14 +58,138 @@ export interface ManagedRelayQueryEvent {
   readonly traceId?: string | null;
 }
 
-export class ManagedRelaySessionError extends Data.TaggedError("ManagedRelaySessionError")<{
-  readonly message: string;
-  readonly cause?: unknown;
-}> {}
+export class ManagedRelayTokenReadError extends Schema.TaggedErrorClass<ManagedRelayTokenReadError>()(
+  "ManagedRelayTokenReadError",
+  {
+    accountId: Schema.String,
+    cause: Schema.Defect(),
+  },
+) {
+  override get message(): string {
+    return `Could not obtain the T3 Cloud session token for account ${this.accountId}.`;
+  }
+}
+
+export class ManagedRelayTokenUnavailableError extends Schema.TaggedErrorClass<ManagedRelayTokenUnavailableError>()(
+  "ManagedRelayTokenUnavailableError",
+  { accountId: Schema.String },
+) {
+  override get message(): string {
+    return `The T3 Cloud session token is unavailable for account ${this.accountId}.`;
+  }
+}
+
+export class ManagedRelaySessionUnavailableError extends Schema.TaggedErrorClass<ManagedRelaySessionUnavailableError>()(
+  "ManagedRelaySessionUnavailableError",
+  { requestedAccountId: Schema.String },
+) {
+  override get message(): string {
+    return `Sign in to T3 Cloud as account ${this.requestedAccountId} before loading relay data.`;
+  }
+}
+
+export const ManagedRelaySessionError = Schema.Union([
+  ManagedRelayTokenReadError,
+  ManagedRelayTokenUnavailableError,
+  ManagedRelaySessionUnavailableError,
+]);
+export type ManagedRelaySessionError = typeof ManagedRelaySessionError.Type;
+
+export class ManagedRelayStatusEnvironmentMismatchError extends Schema.TaggedErrorClass<ManagedRelayStatusEnvironmentMismatchError>()(
+  "ManagedRelayStatusEnvironmentMismatchError",
+  {
+    expectedEnvironmentId: EnvironmentId,
+    actualEnvironmentId: EnvironmentId,
+  },
+) {
+  override get message(): string {
+    return `Relay returned status for environment ${this.actualEnvironmentId} instead of ${this.expectedEnvironmentId}.`;
+  }
+}
+
+export class ManagedRelayStatusEndpointMismatchError extends Schema.TaggedErrorClass<ManagedRelayStatusEndpointMismatchError>()(
+  "ManagedRelayStatusEndpointMismatchError",
+  {
+    environmentId: EnvironmentId,
+    expectedProviderKind: RelayManagedEndpointProviderKind,
+    expectedHttpBaseUrlInputLength: Schema.Number,
+    expectedHttpBaseUrlProtocol: Schema.optionalKey(Schema.String),
+    expectedHttpBaseUrlHostname: Schema.optionalKey(Schema.String),
+    expectedWsBaseUrlInputLength: Schema.Number,
+    expectedWsBaseUrlProtocol: Schema.optionalKey(Schema.String),
+    expectedWsBaseUrlHostname: Schema.optionalKey(Schema.String),
+    actualProviderKind: RelayManagedEndpointProviderKind,
+    actualHttpBaseUrlInputLength: Schema.Number,
+    actualHttpBaseUrlProtocol: Schema.optionalKey(Schema.String),
+    actualHttpBaseUrlHostname: Schema.optionalKey(Schema.String),
+    actualWsBaseUrlInputLength: Schema.Number,
+    actualWsBaseUrlProtocol: Schema.optionalKey(Schema.String),
+    actualWsBaseUrlHostname: Schema.optionalKey(Schema.String),
+  },
+) {
+  static fromEndpoints(input: {
+    readonly environmentId: EnvironmentId;
+    readonly expectedEndpoint: RelayClientEnvironmentRecord["endpoint"];
+    readonly actualEndpoint: RelayClientEnvironmentRecord["endpoint"];
+  }): ManagedRelayStatusEndpointMismatchError {
+    const expectedHttp = getUrlDiagnostics(input.expectedEndpoint.httpBaseUrl);
+    const expectedWs = getUrlDiagnostics(input.expectedEndpoint.wsBaseUrl);
+    const actualHttp = getUrlDiagnostics(input.actualEndpoint.httpBaseUrl);
+    const actualWs = getUrlDiagnostics(input.actualEndpoint.wsBaseUrl);
+    return new ManagedRelayStatusEndpointMismatchError({
+      environmentId: input.environmentId,
+      expectedProviderKind: input.expectedEndpoint.providerKind,
+      expectedHttpBaseUrlInputLength: expectedHttp.inputLength,
+      ...(expectedHttp.protocol === undefined
+        ? {}
+        : { expectedHttpBaseUrlProtocol: expectedHttp.protocol }),
+      ...(expectedHttp.hostname === undefined
+        ? {}
+        : { expectedHttpBaseUrlHostname: expectedHttp.hostname }),
+      expectedWsBaseUrlInputLength: expectedWs.inputLength,
+      ...(expectedWs.protocol === undefined
+        ? {}
+        : { expectedWsBaseUrlProtocol: expectedWs.protocol }),
+      ...(expectedWs.hostname === undefined
+        ? {}
+        : { expectedWsBaseUrlHostname: expectedWs.hostname }),
+      actualProviderKind: input.actualEndpoint.providerKind,
+      actualHttpBaseUrlInputLength: actualHttp.inputLength,
+      ...(actualHttp.protocol === undefined
+        ? {}
+        : { actualHttpBaseUrlProtocol: actualHttp.protocol }),
+      ...(actualHttp.hostname === undefined
+        ? {}
+        : { actualHttpBaseUrlHostname: actualHttp.hostname }),
+      actualWsBaseUrlInputLength: actualWs.inputLength,
+      ...(actualWs.protocol === undefined ? {} : { actualWsBaseUrlProtocol: actualWs.protocol }),
+      ...(actualWs.hostname === undefined ? {} : { actualWsBaseUrlHostname: actualWs.hostname }),
+    });
+  }
+
+  override get message(): string {
+    return `Relay returned a different endpoint for environment ${this.environmentId}.`;
+  }
+}
+
+export class ManagedRelayStatusDescriptorEnvironmentMismatchError extends Schema.TaggedErrorClass<ManagedRelayStatusDescriptorEnvironmentMismatchError>()(
+  "ManagedRelayStatusDescriptorEnvironmentMismatchError",
+  {
+    expectedEnvironmentId: EnvironmentId,
+    actualEnvironmentId: EnvironmentId,
+  },
+) {
+  override get message(): string {
+    return `Relay returned a descriptor for environment ${this.actualEnvironmentId} instead of ${this.expectedEnvironmentId}.`;
+  }
+}
 
-export class ManagedRelaySnapshotError extends Data.TaggedError("ManagedRelaySnapshotError")<{
-  readonly message: string;
-}> {}
+export const ManagedRelaySnapshotError = Schema.Union([
+  ManagedRelayStatusEnvironmentMismatchError,
+  ManagedRelayStatusEndpointMismatchError,
+  ManagedRelayStatusDescriptorEnvironmentMismatchError,
+]);
+export type ManagedRelaySnapshotError = typeof ManagedRelaySnapshotError.Type;
 
 export const managedRelaySessionAtom = Atom.make<ManagedRelaySession | null>(null).pipe(
   Atom.keepAlive,
@@ -122,8 +249,8 @@ export function createManagedRelaySession(input: ManagedRelaySessionInput): Mana
       return yield* Effect.tryPromise({
         try: () => readCachedClerkToken(nowMillis),
         catch: (cause) =>
-          new ManagedRelaySessionError({
-            message: "Could not obtain the T3 Cloud session token.",
+          new ManagedRelayTokenReadError({
+            accountId: input.accountId,
             cause,
           }),
       });
@@ -180,8 +307,8 @@ function readSessionClerkToken(
       token
         ? Effect.succeed(token)
         : Effect.fail(
-            new ManagedRelaySessionError({
-              message: "The T3 Cloud session token is unavailable.",
+            new ManagedRelayTokenUnavailableError({
+              accountId: session.accountId,
             }),
           ),
     ),
@@ -225,8 +352,8 @@ function requireClerkToken(
   const session = get(managedRelaySessionAtom);
   if (!session || session.accountId !== accountId) {
     return Effect.fail(
-      new ManagedRelaySessionError({
-        message: "Sign in to T3 Cloud before loading relay data.",
+      new ManagedRelaySessionUnavailableError({
+        requestedAccountId: accountId,
       }),
     );
   }
@@ -267,22 +394,26 @@ function validateEnvironmentStatus(
 ): Effect.Effect<RelayEnvironmentStatusResponse, ManagedRelaySnapshotError> {
   if (status.environmentId !== environment.environmentId) {
     return Effect.fail(
-      new ManagedRelaySnapshotError({
-        message: "Relay returned status for a different environment.",
+      new ManagedRelayStatusEnvironmentMismatchError({
+        expectedEnvironmentId: environment.environmentId,
+        actualEnvironmentId: status.environmentId,
       }),
     );
   }
   if (!endpointMatches(status.endpoint, environment.endpoint)) {
     return Effect.fail(
-      new ManagedRelaySnapshotError({
-        message: "Relay returned status for a different endpoint.",
+      ManagedRelayStatusEndpointMismatchError.fromEndpoints({
+        environmentId: environment.environmentId,
+        expectedEndpoint: environment.endpoint,
+        actualEndpoint: status.endpoint,
       }),
     );
   }
   if (status.descriptor && status.descriptor.environmentId !== environment.environmentId) {
     return Effect.fail(
-      new ManagedRelaySnapshotError({
-        message: "Relay returned status descriptor for a different environment.",
+      new ManagedRelayStatusDescriptorEnvironmentMismatchError({
+        expectedEnvironmentId: environment.environmentId,
+        actualEnvironmentId: status.descriptor.environmentId,
       }),
     );
   }
diff --git a/packages/client-runtime/src/rpc/client.test.ts b/packages/client-runtime/src/rpc/client.test.ts
index 507d137cacc..64d06184dc3 100644
--- a/packages/client-runtime/src/rpc/client.test.ts
+++ b/packages/client-runtime/src/rpc/client.test.ts
@@ -25,7 +25,13 @@ import {
 import * as EnvironmentSupervisor from "../connection/supervisor.ts";
 import * as RpcSession from "../rpc/session.ts";
 import type { WsRpcProtocolClient } from "../rpc/protocol.ts";
-import { EnvironmentRpcRequestObserver, request, runStream, subscribe } from "./client.ts";
+import {
+  EnvironmentRpcRequestObserver,
+  EnvironmentRpcUnavailableError,
+  request,
+  runStream,
+  subscribe,
+} from "./client.ts";
 
 const TARGET = new PrimaryConnectionTarget({
   environmentId: EnvironmentId.make("environment-1"),
@@ -77,6 +83,27 @@ const makeHarness = Effect.fn("TestEnvironmentRpc.makeHarness")(function* () {
 });
 
 describe("environment RPC", () => {
+  it.effect("reports the disconnected environment and requested method", () =>
+    Effect.gen(function* () {
+      const { supervisor } = yield* makeHarness();
+
+      const error = yield* request(WS_METHODS.cloudGetRelayClientStatus, {}).pipe(
+        Effect.flip,
+        Effect.provideService(EnvironmentSupervisor.EnvironmentSupervisor, supervisor),
+      );
+
+      expect(error).toBeInstanceOf(EnvironmentRpcUnavailableError);
+      expect(error).toMatchObject({
+        environmentId: TARGET.environmentId,
+        environmentLabel: TARGET.label,
+        method: WS_METHODS.cloudGetRelayClientStatus,
+      });
+      expect(error.message).toBe(
+        `Test environment is not connected for RPC method ${WS_METHODS.cloudGetRelayClientStatus}.`,
+      );
+    }),
+  );
+
   it.effect("observes unary requests until they complete", () =>
     Effect.gen(function* () {
       const observations: string[] = [];
diff --git a/packages/client-runtime/src/rpc/client.ts b/packages/client-runtime/src/rpc/client.ts
index 92892431e45..1e136768c19 100644
--- a/packages/client-runtime/src/rpc/client.ts
+++ b/packages/client-runtime/src/rpc/client.ts
@@ -1,4 +1,4 @@
-import { ORCHESTRATION_WS_METHODS, WS_METHODS } from "@t3tools/contracts";
+import { EnvironmentId, ORCHESTRATION_WS_METHODS, WS_METHODS } from "@t3tools/contracts";
 import * as Cause from "effect/Cause";
 import * as Context from "effect/Context";
 import type * as Duration from "effect/Duration";
@@ -15,10 +15,18 @@ import type { WsRpcProtocolClient } from "../rpc/protocol.ts";
 export class EnvironmentRpcUnavailableError extends Schema.TaggedErrorClass<EnvironmentRpcUnavailableError>()(
   "EnvironmentRpcUnavailableError",
   {
-    environmentId: Schema.String,
-    message: Schema.String,
+    environmentId: EnvironmentId,
+    environmentLabel: Schema.String,
+    method: Schema.optionalKey(Schema.String),
   },
-) {}
+) {
+  override get message(): string {
+    const method = this.method === undefined ? "" : ` for RPC method ${this.method}`;
+    return `${this.environmentLabel} is not connected${method}.`;
+  }
+}
+
+export const isEnvironmentRpcUnavailableError = Schema.is(EnvironmentRpcUnavailableError);
 
 export interface EnvironmentRpcRequestObservation {
   readonly environmentId: string;
@@ -85,7 +93,7 @@ export type EnvironmentRpcStreamFailure<TTag extends EnvironmentStreamRpcTag> =
     ? E
     : never;
 
-const currentSession = Effect.fn("EnvironmentRpc.currentSession")(function* () {
+const currentSession = Effect.fn("EnvironmentRpc.currentSession")(function* (method?: string) {
   const supervisor = yield* EnvironmentSupervisor;
   return yield* SubscriptionRef.get(supervisor.session).pipe(
     Effect.flatMap(
@@ -94,7 +102,8 @@ const currentSession = Effect.fn("EnvironmentRpc.currentSession")(function* () {
           Effect.fail(
             new EnvironmentRpcUnavailableError({
               environmentId: supervisor.target.environmentId,
-              message: `${supervisor.target.label} is not connected.`,
+              environmentLabel: supervisor.target.label,
+              ...(method === undefined ? {} : { method }),
             }),
           ),
         onSome: Effect.succeed,
@@ -111,7 +120,7 @@ export const request = Effect.fn("EnvironmentRpc.request")(function* <
     "environment.id": supervisor.target.environmentId,
     "rpc.method": tag,
   });
-  const session = yield* currentSession();
+  const session = yield* currentSession(tag);
   const observer = yield* EnvironmentRpcRequestObserver;
   const method = session.client[tag] as (
     input: EnvironmentRpcInput<TTag>,
@@ -132,7 +141,7 @@ export function runStream<TTag extends EnvironmentStreamCommandRpcTag>(
   EnvironmentSupervisor
 > {
   return Stream.unwrap(
-    currentSession().pipe(
+    currentSession(tag).pipe(
       Effect.map((session) => {
         const method = session.client[tag] as (
           input: EnvironmentRpcInput<TTag>,
@@ -195,7 +204,8 @@ export function subscribe<TTag extends EnvironmentSubscriptionRpcTag>(
                             Effect.logWarning(
                               "Durable RPC subscription lost its transport; waiting for the next session.",
                               {
-                                cause: Cause.pretty(cause),
+                                errorTag: "RpcClientError",
+                                reasonCount: cause.reasons.length,
                                 method: tag,
                                 environmentId: supervisor.target.environmentId,
                               },
diff --git a/packages/client-runtime/src/rpc/http.ts b/packages/client-runtime/src/rpc/http.ts
index 11bfa794fa7..4b0514df747 100644
--- a/packages/client-runtime/src/rpc/http.ts
+++ b/packages/client-runtime/src/rpc/http.ts
@@ -8,63 +8,131 @@ import {
   type EnvironmentScopeRequiredError,
 } from "@t3tools/contracts";
 import { httpHeaderRedactionLayer } from "@t3tools/shared/httpObservability";
-import * as Data from "effect/Data";
+import { getUrlDiagnostics } from "@t3tools/shared/urlDiagnostics";
 import * as Duration from "effect/Duration";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as Option from "effect/Option";
 import * as Schema from "effect/Schema";
-import { FetchHttpClient, HttpClient, HttpClientError } from "effect/unstable/http";
+import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
+import * as HttpClient from "effect/unstable/http/HttpClient";
+import * as HttpClientError from "effect/unstable/http/HttpClientError";
 import * as HttpApiClient from "effect/unstable/httpapi/HttpApiClient";
 
 const isEnvironmentHttpCommonError = Schema.is(EnvironmentHttpCommonError);
 
-export class RemoteEnvironmentAuthFetchError extends Data.TaggedError(
+const requestUrlDiagnosticSchema = {
+  requestUrlInputLength: Schema.Number,
+  requestUrlProtocol: Schema.optionalKey(Schema.String),
+  requestUrlHostname: Schema.optionalKey(Schema.String),
+} as const;
+
+function requestUrlDiagnosticFields(requestUrl: string) {
+  const diagnostics = getUrlDiagnostics(requestUrl);
+  return {
+    requestUrlInputLength: diagnostics.inputLength,
+    ...(diagnostics.protocol === undefined ? {} : { requestUrlProtocol: diagnostics.protocol }),
+    ...(diagnostics.hostname === undefined ? {} : { requestUrlHostname: diagnostics.hostname }),
+  };
+}
+
+function requestUrlDescription(input: {
+  readonly requestUrlInputLength: number;
+  readonly requestUrlHostname?: string;
+}): string {
+  return input.requestUrlHostname === undefined
+    ? `an invalid URL (${input.requestUrlInputLength} characters)`
+    : `host ${input.requestUrlHostname} (${input.requestUrlInputLength} URL characters)`;
+}
+
+export class RemoteEnvironmentAuthFetchError extends Schema.TaggedErrorClass<RemoteEnvironmentAuthFetchError>()(
   "RemoteEnvironmentAuthFetchError",
-)<{
-  readonly message: string;
-  readonly cause: unknown;
-}> {}
+  {
+    ...requestUrlDiagnosticSchema,
+    cause: Schema.Defect(),
+  },
+) {
+  static fromRequestUrl(requestUrl: string, cause: unknown): RemoteEnvironmentAuthFetchError {
+    return new RemoteEnvironmentAuthFetchError({
+      ...requestUrlDiagnosticFields(requestUrl),
+      cause,
+    });
+  }
+
+  override get message(): string {
+    return `Failed to fetch remote environment endpoint at ${requestUrlDescription(this)}.`;
+  }
+}
 
-export class RemoteEnvironmentAuthInvalidJsonError extends Data.TaggedError(
+export class RemoteEnvironmentAuthInvalidJsonError extends Schema.TaggedErrorClass<RemoteEnvironmentAuthInvalidJsonError>()(
   "RemoteEnvironmentAuthInvalidJsonError",
-)<{
-  readonly message: string;
-  readonly cause: unknown;
-}> {}
+  {
+    ...requestUrlDiagnosticSchema,
+    cause: Schema.Defect(),
+  },
+) {
+  static fromRequestUrl(requestUrl: string, cause: unknown): RemoteEnvironmentAuthInvalidJsonError {
+    return new RemoteEnvironmentAuthInvalidJsonError({
+      ...requestUrlDiagnosticFields(requestUrl),
+      cause,
+    });
+  }
 
-export class RemoteEnvironmentAuthUndeclaredStatusError extends Data.TaggedError(
+  override get message(): string {
+    return `Remote environment endpoint at ${requestUrlDescription(this)} returned an invalid response.`;
+  }
+}
+
+export class RemoteEnvironmentAuthUndeclaredStatusError extends Schema.TaggedErrorClass<RemoteEnvironmentAuthUndeclaredStatusError>()(
   "RemoteEnvironmentAuthUndeclaredStatusError",
-)<{
-  readonly message: string;
-  readonly status: number;
-  readonly requestUrl: string;
-}> {
-  constructor(requestUrl: string, status: number) {
-    super({
-      message: `Remote environment endpoint ${requestUrl} returned undeclared status ${status}.`,
-      requestUrl,
+  {
+    ...requestUrlDiagnosticSchema,
+    status: Schema.Number,
+    cause: Schema.Defect(),
+  },
+) {
+  static fromRequestUrl(
+    requestUrl: string,
+    status: number,
+    cause: unknown,
+  ): RemoteEnvironmentAuthUndeclaredStatusError {
+    return new RemoteEnvironmentAuthUndeclaredStatusError({
+      ...requestUrlDiagnosticFields(requestUrl),
       status,
+      cause,
     });
   }
+
+  override get message(): string {
+    return `Remote environment endpoint at ${requestUrlDescription(this)} returned undeclared status ${this.status}.`;
+  }
 }
 
-export class RemoteEnvironmentAuthTimeoutError extends Data.TaggedError(
+export const isRemoteEnvironmentAuthUndeclaredStatusError = Schema.is(
+  RemoteEnvironmentAuthUndeclaredStatusError,
+);
+
+export class RemoteEnvironmentAuthTimeoutError extends Schema.TaggedErrorClass<RemoteEnvironmentAuthTimeoutError>()(
   "RemoteEnvironmentAuthTimeoutError",
-)<{
-  readonly message: string;
-  readonly requestUrl: string;
-  readonly timeoutMs: number;
-}> {
-  constructor(requestUrl: string, timeoutMs: number) {
-    super({
-      message: `Remote environment endpoint ${requestUrl} timed out after ${timeoutMs}ms.`,
-      requestUrl,
+  {
+    ...requestUrlDiagnosticSchema,
+    timeoutMs: Schema.Number,
+  },
+) {
+  static fromRequestUrl(requestUrl: string, timeoutMs: number): RemoteEnvironmentAuthTimeoutError {
+    return new RemoteEnvironmentAuthTimeoutError({
+      ...requestUrlDiagnosticFields(requestUrl),
       timeoutMs,
     });
   }
+
+  override get message(): string {
+    return `Remote environment endpoint at ${requestUrlDescription(this)} timed out after ${this.timeoutMs}ms.`;
+  }
 }
 
+const isRemoteEnvironmentAuthTimeoutError = Schema.is(RemoteEnvironmentAuthTimeoutError);
+
 export type RemoteEnvironmentRequestError =
   | EnvironmentRequestInvalidError
   | EnvironmentAuthInvalidError
@@ -101,40 +169,29 @@ const failRemoteRequest = (
   requestUrl: string,
   cause: unknown,
 ): Effect.Effect<never, RemoteEnvironmentRequestError> => {
-  if (cause instanceof RemoteEnvironmentAuthTimeoutError) {
+  if (isRemoteEnvironmentAuthTimeoutError(cause)) {
     return Effect.fail(cause);
   }
   if (isEnvironmentHttpCommonError(cause)) {
     return Effect.fail(cause);
   }
   if (Schema.isSchemaError(cause)) {
-    return Effect.fail(
-      new RemoteEnvironmentAuthInvalidJsonError({
-        message: `Remote environment endpoint returned an invalid response from ${requestUrl}.`,
-        cause,
-      }),
-    );
+    return Effect.fail(RemoteEnvironmentAuthInvalidJsonError.fromRequestUrl(requestUrl, cause));
   }
   if (HttpClientError.isHttpClientError(cause) && cause.response !== undefined) {
     const response = cause.response;
     if (response.status < 200 || response.status >= 300) {
       return Effect.fail(
-        new RemoteEnvironmentAuthUndeclaredStatusError(requestUrl, response.status),
+        RemoteEnvironmentAuthUndeclaredStatusError.fromRequestUrl(
+          requestUrl,
+          response.status,
+          cause,
+        ),
       );
     }
-    return Effect.fail(
-      new RemoteEnvironmentAuthInvalidJsonError({
-        message: `Remote environment endpoint returned an invalid response from ${requestUrl}.`,
-        cause,
-      }),
-    );
+    return Effect.fail(RemoteEnvironmentAuthInvalidJsonError.fromRequestUrl(requestUrl, cause));
   }
-  return Effect.fail(
-    new RemoteEnvironmentAuthFetchError({
-      message: `Failed to fetch remote environment endpoint ${requestUrl} (${String(cause)}).`,
-      cause,
-    }),
-  );
+  return Effect.fail(RemoteEnvironmentAuthFetchError.fromRequestUrl(requestUrl, cause));
 };
 
 export const executeEnvironmentHttpRequest = <A, E, R>(
@@ -146,7 +203,8 @@ export const executeEnvironmentHttpRequest = <A, E, R>(
     Effect.timeoutOption(Duration.millis(timeoutMs)),
     Effect.flatMap(
       Option.match({
-        onNone: () => Effect.fail(new RemoteEnvironmentAuthTimeoutError(requestUrl, timeoutMs)),
+        onNone: () =>
+          Effect.fail(RemoteEnvironmentAuthTimeoutError.fromRequestUrl(requestUrl, timeoutMs)),
         onSome: Effect.succeed,
       }),
     ),
diff --git a/packages/client-runtime/src/rpc/session.ts b/packages/client-runtime/src/rpc/session.ts
index f9594c1b7ca..c651ac697d3 100644
--- a/packages/client-runtime/src/rpc/session.ts
+++ b/packages/client-runtime/src/rpc/session.ts
@@ -49,17 +49,20 @@ function mapInitialConfigError(error: InitialConfigError): ConnectionAttemptErro
       return new ConnectionBlockedError({
         reason: "permission",
         detail: error.message,
+        cause: error,
       });
-    case "KeybindingsConfigParseError":
+    case "KeybindingsConfigError":
     case "ServerSettingsError":
       return new ConnectionTransientErrorClass({
         reason: "remote-unavailable",
         detail: error.message,
+        cause: error,
       });
     case "RpcClientError":
       return new ConnectionTransientErrorClass({
         reason: "transport",
         detail: error.message,
+        cause: error,
       });
   }
 }
diff --git a/packages/contracts/src/auth.test.ts b/packages/contracts/src/auth.test.ts
new file mode 100644
index 00000000000..7052b2debdd
--- /dev/null
+++ b/packages/contracts/src/auth.test.ts
@@ -0,0 +1,38 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import { AuthSessionId } from "./baseSchemas.ts";
+import { AuthAccessStreamError } from "./auth.ts";
+
+describe("AuthAccessStreamError", () => {
+  it("preserves the pairing-link list failure", () => {
+    const cause = new Error("database unavailable");
+    const error = new AuthAccessStreamError({
+      operation: "list-pairing-links",
+      cause,
+    });
+
+    expect(error.operation).toBe("list-pairing-links");
+    expect(error.currentSessionId).toBeUndefined();
+    expect(error.cause).toBe(cause);
+    expect(error.message).toBe("Authentication access stream operation list-pairing-links failed.");
+    expect(error.message).not.toContain(cause.message);
+  });
+
+  it("preserves the current session for client-session list failures", () => {
+    const cause = new Error("database unavailable");
+    const currentSessionId = AuthSessionId.make("session-current");
+    const error = new AuthAccessStreamError({
+      operation: "list-client-sessions",
+      currentSessionId,
+      cause,
+    });
+
+    expect(error.operation).toBe("list-client-sessions");
+    expect(error.currentSessionId).toBe(currentSessionId);
+    expect(error.cause).toBe(cause);
+    expect(error.message).toBe(
+      "Authentication access stream operation list-client-sessions failed for session session-current.",
+    );
+    expect(error.message).not.toContain(cause.message);
+  });
+});
diff --git a/packages/contracts/src/auth.ts b/packages/contracts/src/auth.ts
index 70b2899757d..04467729abc 100644
--- a/packages/contracts/src/auth.ts
+++ b/packages/contracts/src/auth.ts
@@ -276,12 +276,26 @@ export const AuthAccessStreamPairingLinkRemovedEvent = Schema.Struct({
 export type AuthAccessStreamPairingLinkRemovedEvent =
   typeof AuthAccessStreamPairingLinkRemovedEvent.Type;
 
+export const AuthAccessStreamOperation = Schema.Literals([
+  "list-pairing-links",
+  "list-client-sessions",
+]);
+export type AuthAccessStreamOperation = typeof AuthAccessStreamOperation.Type;
+
 export class AuthAccessStreamError extends Schema.TaggedErrorClass<AuthAccessStreamError>()(
   "AuthAccessStreamError",
   {
-    message: Schema.String,
+    operation: AuthAccessStreamOperation,
+    currentSessionId: Schema.optional(AuthSessionId),
+    cause: Schema.Defect(),
   },
-) {}
+) {
+  override get message(): string {
+    const session =
+      this.currentSessionId === undefined ? "" : ` for session ${this.currentSessionId}`;
+    return `Authentication access stream operation ${this.operation} failed${session}.`;
+  }
+}
 
 export class EnvironmentAuthorizationError extends Schema.TaggedErrorClass<EnvironmentAuthorizationError>()(
   "EnvironmentAuthorizationError",
diff --git a/packages/contracts/src/environmentHttp.test.ts b/packages/contracts/src/environmentHttp.test.ts
new file mode 100644
index 00000000000..8aa2b6c8121
--- /dev/null
+++ b/packages/contracts/src/environmentHttp.test.ts
@@ -0,0 +1,54 @@
+import { assert, describe, it } from "@effect/vitest";
+
+import {
+  EnvironmentAuthInvalidError,
+  EnvironmentInternalError,
+  EnvironmentOperationForbiddenError,
+  EnvironmentRequestInvalidError,
+  EnvironmentScopeRequiredError,
+} from "./environmentHttp.ts";
+
+describe("environment HTTP common errors", () => {
+  it("derives messages from structural diagnostics", () => {
+    assert.equal(
+      new EnvironmentRequestInvalidError({
+        code: "invalid_request",
+        reason: "invalid_scope",
+        traceId: "trace-request",
+      }).message,
+      "Environment request rejected with invalid_request (invalid_scope; trace trace-request).",
+    );
+    assert.equal(
+      new EnvironmentAuthInvalidError({
+        code: "auth_invalid",
+        reason: "invalid_credential",
+        traceId: "trace-auth",
+      }).message,
+      "Environment authentication rejected with auth_invalid (invalid_credential; trace trace-auth).",
+    );
+    assert.equal(
+      new EnvironmentScopeRequiredError({
+        code: "insufficient_scope",
+        requiredScope: "access:read",
+        traceId: "trace-scope",
+      }).message,
+      "Environment authorization requires scope access:read (insufficient_scope; trace trace-scope).",
+    );
+    assert.equal(
+      new EnvironmentOperationForbiddenError({
+        code: "operation_forbidden",
+        reason: "current_session_revoke_not_allowed",
+        traceId: "trace-forbidden",
+      }).message,
+      "Environment operation rejected with operation_forbidden (current_session_revoke_not_allowed; trace trace-forbidden).",
+    );
+    assert.equal(
+      new EnvironmentInternalError({
+        code: "internal_error",
+        reason: "access_token_issuance_failed",
+        traceId: "trace-internal",
+      }).message,
+      "Environment request failed with internal_error (access_token_issuance_failed; trace trace-internal).",
+    );
+  });
+});
diff --git a/packages/contracts/src/environmentHttp.ts b/packages/contracts/src/environmentHttp.ts
index adc5f149cba..232cd8012cc 100644
--- a/packages/contracts/src/environmentHttp.ts
+++ b/packages/contracts/src/environmentHttp.ts
@@ -94,6 +94,10 @@ export class EnvironmentRequestInvalidError extends Schema.TaggedErrorClass<Envi
   },
   { httpApiStatus: 400 },
 ) {
+  override get message(): string {
+    return `Environment request rejected with ${this.code} (${this.reason}; trace ${this.traceId}).`;
+  }
+
   [HttpServerRespondable.symbol]() {
     return HttpServerResponse.schemaJson(EnvironmentRequestInvalidError)(this, { status: 400 });
   }
@@ -108,6 +112,10 @@ export class EnvironmentAuthInvalidError extends Schema.TaggedErrorClass<Environ
   },
   { httpApiStatus: 401 },
 ) {
+  override get message(): string {
+    return `Environment authentication rejected with ${this.code} (${this.reason}; trace ${this.traceId}).`;
+  }
+
   [HttpServerRespondable.symbol]() {
     return HttpServerResponse.schemaJson(EnvironmentAuthInvalidError)(this, { status: 401 });
   }
@@ -122,6 +130,10 @@ export class EnvironmentScopeRequiredError extends Schema.TaggedErrorClass<Envir
   },
   { httpApiStatus: 403 },
 ) {
+  override get message(): string {
+    return `Environment authorization requires scope ${this.requiredScope} (${this.code}; trace ${this.traceId}).`;
+  }
+
   [HttpServerRespondable.symbol]() {
     return HttpServerResponse.schemaJson(EnvironmentScopeRequiredError)(this, { status: 403 });
   }
@@ -136,6 +148,10 @@ export class EnvironmentOperationForbiddenError extends Schema.TaggedErrorClass<
   },
   { httpApiStatus: 403 },
 ) {
+  override get message(): string {
+    return `Environment operation rejected with ${this.code} (${this.reason}; trace ${this.traceId}).`;
+  }
+
   [HttpServerRespondable.symbol]() {
     return HttpServerResponse.schemaJson(EnvironmentOperationForbiddenError)(this, { status: 403 });
   }
@@ -150,6 +166,10 @@ export class EnvironmentInternalError extends Schema.TaggedErrorClass<Environmen
   },
   { httpApiStatus: 500 },
 ) {
+  override get message(): string {
+    return `Environment request failed with ${this.code} (${this.reason}; trace ${this.traceId}).`;
+  }
+
   [HttpServerRespondable.symbol]() {
     return HttpServerResponse.schemaJson(EnvironmentInternalError)(this, { status: 500 });
   }
@@ -169,13 +189,154 @@ const EnvironmentAuthenticationErrors = [
   EnvironmentInternalError,
 ] as const;
 
+export const EnvironmentHttpBadRequestReason = Schema.Literals([
+  "invalid_cloud_mint_public_key",
+  "invalid_relay_url",
+  "invalid_relay_issuer",
+  "missing_relay_environment_credential",
+  "missing_cloud_user_id",
+  "invalid_managed_endpoint_origin",
+  "invalid_local_environment_origin",
+]);
+export type EnvironmentHttpBadRequestReason = typeof EnvironmentHttpBadRequestReason.Type;
+
+const environmentHttpBadRequestMessages = {
+  invalid_cloud_mint_public_key: "Cloud mint public key must be a valid Ed25519 public key.",
+  invalid_relay_url: "Relay URL must be a secure absolute HTTPS URL.",
+  invalid_relay_issuer: "Relay issuer must be a secure absolute HTTPS URL.",
+  missing_relay_environment_credential: "Relay environment credential is required.",
+  missing_cloud_user_id: "Cloud user id is required.",
+  invalid_managed_endpoint_origin: "Invalid managed endpoint origin.",
+  invalid_local_environment_origin: "Could not resolve local environment origin.",
+} satisfies Record<EnvironmentHttpBadRequestReason, string>;
+
+export const EnvironmentHttpUnauthorizedReason = Schema.Literals([
+  "cloud_cli_authorization_required",
+  "invalid_cloud_health_request",
+  "invalid_cloud_mint_request",
+]);
+export type EnvironmentHttpUnauthorizedReason = typeof EnvironmentHttpUnauthorizedReason.Type;
+
+const environmentHttpUnauthorizedMessages = {
+  cloud_cli_authorization_required: "Run `t3 connect link` to authorize this environment.",
+  invalid_cloud_health_request: "Invalid cloud health request.",
+  invalid_cloud_mint_request: "Invalid cloud mint request.",
+} satisfies Record<EnvironmentHttpUnauthorizedReason, string>;
+
+export const EnvironmentHttpInternalOperation = Schema.Literals([
+  "generate_link_proof",
+  "verify_linked_cloud_account",
+  "persist_relay_configuration",
+  "persist_desired_link_state",
+  "read_relay_configuration",
+  "remove_relay_configuration",
+  "persist_cloud_preferences",
+  "answer_cloud_health_request",
+  "issue_cloud_connection_credential",
+  "read_linked_cloud_account",
+  "require_linked_cloud_account",
+  "sign_cloud_link_jwt",
+  "read_cloud_mint_public_key",
+  "read_cloud_relay_issuer",
+  "sign_cloud_health_jwt",
+  "sign_cloud_mint_jwt",
+  "create_cloud_pairing_link",
+  "read_relay_url_configuration",
+  "relay_request",
+  "remove_cloud_cli_credential",
+  "refresh_cloud_cli_credential",
+  "read_cloud_cli_credential",
+  "authorize_cloud_cli",
+  "await_cloud_cli_authorization",
+]);
+export type EnvironmentHttpInternalOperation = typeof EnvironmentHttpInternalOperation.Type;
+
+export const EnvironmentHttpRelayOperation = Schema.Literals([
+  "create-link-challenge",
+  "create-environment-link",
+]);
+export type EnvironmentHttpRelayOperation = typeof EnvironmentHttpRelayOperation.Type;
+
+export const EnvironmentHttpRelayPhase = Schema.Literals([
+  "encode-request",
+  "send-request",
+  "check-response-status",
+  "decode-response",
+]);
+export type EnvironmentHttpRelayPhase = typeof EnvironmentHttpRelayPhase.Type;
+
+const environmentHttpInternalMessages = {
+  generate_link_proof: "Could not generate environment link proof.",
+  verify_linked_cloud_account: "Could not verify the linked cloud account.",
+  persist_relay_configuration: "Could not persist environment relay configuration.",
+  persist_desired_link_state: "Could not persist desired T3 Connect link state.",
+  read_relay_configuration: "Could not read environment relay configuration.",
+  remove_relay_configuration: "Could not remove environment relay configuration.",
+  persist_cloud_preferences: "Could not persist environment cloud preferences.",
+  answer_cloud_health_request: "Could not answer cloud health request.",
+  issue_cloud_connection_credential: "Could not issue cloud connection credential.",
+  read_linked_cloud_account: "Could not read the linked cloud account.",
+  require_linked_cloud_account: "Cloud linked user is not installed for this environment.",
+  sign_cloud_link_jwt: "Failed to sign cloud link JWT.",
+  read_cloud_mint_public_key: "Cloud mint public key is not installed for this environment.",
+  read_cloud_relay_issuer: "Cloud relay issuer is not installed for this environment.",
+  sign_cloud_health_jwt: "Failed to sign cloud health JWT.",
+  sign_cloud_mint_jwt: "Failed to sign cloud mint JWT.",
+  create_cloud_pairing_link: "Failed to create pairing link.",
+  read_relay_url_configuration:
+    "T3CODE_RELAY_URL must be configured as a secure absolute HTTPS origin.",
+  remove_cloud_cli_credential: "Could not remove the stored T3 Connect CLI credential.",
+  refresh_cloud_cli_credential: "Could not refresh the T3 Connect CLI credential.",
+  read_cloud_cli_credential: "Could not read the stored T3 Connect CLI credential.",
+  authorize_cloud_cli: "Could not authorize the T3 Connect CLI.",
+  await_cloud_cli_authorization: "Timed out waiting for T3 Connect authorization.",
+} satisfies Record<Exclude<EnvironmentHttpInternalOperation, "relay_request">, string>;
+
+export const EnvironmentHttpConflictReason = Schema.Literals([
+  "linked_to_different_cloud_account",
+  "cloud_health_request_replayed",
+  "cloud_mint_request_replayed",
+]);
+export type EnvironmentHttpConflictReason = typeof EnvironmentHttpConflictReason.Type;
+
+const environmentHttpConflictMessages = {
+  linked_to_different_cloud_account:
+    "This environment is already linked to a different cloud account. Unlink it before switching accounts.",
+  cloud_health_request_replayed: "Cloud health request was already consumed.",
+  cloud_mint_request_replayed: "Cloud mint request was already consumed.",
+} satisfies Record<EnvironmentHttpConflictReason, string>;
+
+// These HTTP errors cross independently deployed clients, relays, and environment servers. Keep
+// newly added diagnostics optional while decoding so a newer peer can still consume the legacy
+// message-only payload. The constructors below continue to require structured context from new
+// application code and only preserve `message` when Schema is decoding an older wire payload.
+function decodedEnvironmentHttpErrorMessage(props: object): string | undefined {
+  if (!("message" in props)) return undefined;
+  return typeof props.message === "string" ? props.message : undefined;
+}
+
 export class EnvironmentHttpBadRequestError extends Schema.TaggedErrorClass<EnvironmentHttpBadRequestError>()(
   "EnvironmentHttpBadRequestError",
   {
+    reason: Schema.optional(EnvironmentHttpBadRequestReason),
     message: Schema.String,
   },
   { httpApiStatus: 400 },
 ) {
+  // @effect-diagnostics-next-line overriddenSchemaConstructor:off
+  constructor(props: {
+    readonly reason: EnvironmentHttpBadRequestReason;
+    readonly cause?: unknown;
+  }) {
+    super({
+      reason: props.reason,
+      message:
+        decodedEnvironmentHttpErrorMessage(props) ??
+        environmentHttpBadRequestMessages[props.reason],
+      ...(props.cause === undefined ? {} : { cause: props.cause }),
+    } as any);
+  }
+
   [HttpServerRespondable.symbol]() {
     return HttpServerResponse.schemaJson(EnvironmentHttpBadRequestError)(this, { status: 400 });
   }
@@ -184,10 +345,25 @@ export class EnvironmentHttpBadRequestError extends Schema.TaggedErrorClass<Envi
 export class EnvironmentHttpUnauthorizedError extends Schema.TaggedErrorClass<EnvironmentHttpUnauthorizedError>()(
   "EnvironmentHttpUnauthorizedError",
   {
+    reason: Schema.optional(EnvironmentHttpUnauthorizedReason),
     message: Schema.String,
   },
   { httpApiStatus: 401 },
 ) {
+  // @effect-diagnostics-next-line overriddenSchemaConstructor:off
+  constructor(props: {
+    readonly reason: EnvironmentHttpUnauthorizedReason;
+    readonly cause?: unknown;
+  }) {
+    super({
+      reason: props.reason,
+      message:
+        decodedEnvironmentHttpErrorMessage(props) ??
+        environmentHttpUnauthorizedMessages[props.reason],
+      ...(props.cause === undefined ? {} : { cause: props.cause }),
+    } as any);
+  }
+
   [HttpServerRespondable.symbol]() {
     return HttpServerResponse.schemaJson(EnvironmentHttpUnauthorizedError)(this, { status: 401 });
   }
@@ -200,6 +376,14 @@ export class EnvironmentHttpForbiddenError extends Schema.TaggedErrorClass<Envir
   },
   { httpApiStatus: 403 },
 ) {
+  // @effect-diagnostics-next-line overriddenSchemaConstructor:off
+  constructor(props: { readonly cause?: unknown } = {}) {
+    super({
+      message: decodedEnvironmentHttpErrorMessage(props) ?? "Cloud operation is forbidden.",
+      ...(props.cause === undefined ? {} : { cause: props.cause }),
+    } as any);
+  }
+
   [HttpServerRespondable.symbol]() {
     return HttpServerResponse.schemaJson(EnvironmentHttpForbiddenError)(this, { status: 403 });
   }
@@ -208,10 +392,44 @@ export class EnvironmentHttpForbiddenError extends Schema.TaggedErrorClass<Envir
 export class EnvironmentHttpInternalServerError extends Schema.TaggedErrorClass<EnvironmentHttpInternalServerError>()(
   "EnvironmentHttpInternalServerError",
   {
+    operation: Schema.optional(EnvironmentHttpInternalOperation),
+    relayOperation: Schema.optional(EnvironmentHttpRelayOperation),
+    relayPhase: Schema.optional(EnvironmentHttpRelayPhase),
+    responseStatus: Schema.optional(Schema.Number),
     message: Schema.String,
   },
   { httpApiStatus: 500 },
 ) {
+  // @effect-diagnostics-next-line overriddenSchemaConstructor:off
+  constructor(
+    props:
+      | {
+          readonly operation: Exclude<EnvironmentHttpInternalOperation, "relay_request">;
+          readonly cause?: unknown;
+        }
+      | {
+          readonly operation: "relay_request";
+          readonly relayOperation: EnvironmentHttpRelayOperation;
+          readonly relayPhase: EnvironmentHttpRelayPhase;
+          readonly responseStatus?: number;
+          readonly cause?: unknown;
+        },
+  ) {
+    const message =
+      decodedEnvironmentHttpErrorMessage(props) ??
+      (props.operation === "relay_request"
+        ? `T3 Connect relay ${props.relayOperation} failed during ${props.relayPhase}${
+            props.responseStatus === undefined
+              ? ""
+              : ` with response status ${props.responseStatus}`
+          }.`
+        : environmentHttpInternalMessages[props.operation]);
+    super({
+      ...props,
+      message,
+    } as any);
+  }
+
   [HttpServerRespondable.symbol]() {
     return HttpServerResponse.schemaJson(EnvironmentHttpInternalServerError)(this, { status: 500 });
   }
@@ -220,10 +438,21 @@ export class EnvironmentHttpInternalServerError extends Schema.TaggedErrorClass<
 export class EnvironmentHttpConflictError extends Schema.TaggedErrorClass<EnvironmentHttpConflictError>()(
   "EnvironmentHttpConflictError",
   {
+    reason: Schema.optional(EnvironmentHttpConflictReason),
     message: Schema.String,
   },
   { httpApiStatus: 409 },
 ) {
+  // @effect-diagnostics-next-line overriddenSchemaConstructor:off
+  constructor(props: { readonly reason: EnvironmentHttpConflictReason; readonly cause?: unknown }) {
+    super({
+      reason: props.reason,
+      message:
+        decodedEnvironmentHttpErrorMessage(props) ?? environmentHttpConflictMessages[props.reason],
+      ...(props.cause === undefined ? {} : { cause: props.cause }),
+    } as any);
+  }
+
   [HttpServerRespondable.symbol]() {
     return HttpServerResponse.schemaJson(EnvironmentHttpConflictError)(this, { status: 409 });
   }
@@ -237,6 +466,16 @@ export class EnvironmentCloudEndpointUnavailableError extends Schema.TaggedError
   },
   { httpApiStatus: 503 },
 ) {
+  // @effect-diagnostics-next-line overriddenSchemaConstructor:off
+  constructor(props: { readonly endpointRuntimeStatus: unknown; readonly cause?: unknown }) {
+    super({
+      ...props,
+      message:
+        decodedEnvironmentHttpErrorMessage(props) ??
+        "Managed endpoint runtime could not be started.",
+    } as any);
+  }
+
   [HttpServerRespondable.symbol]() {
     return HttpServerResponse.schemaJson(EnvironmentCloudEndpointUnavailableError)(this, {
       status: 503,
diff --git a/packages/contracts/src/ipc.ts b/packages/contracts/src/ipc.ts
index 9d6ed04c286..fbdbf5a34fb 100644
--- a/packages/contracts/src/ipc.ts
+++ b/packages/contracts/src/ipc.ts
@@ -329,12 +329,35 @@ export const DesktopSshPasswordPromptRequestSchema = Schema.Struct({
   expiresAt: Schema.String,
 });
 
-export const DesktopSshPasswordPromptCancelledType = "ssh-password-prompt-cancelled" as const;
+export const DesktopSshPasswordPromptCancellationErrorTag =
+  "DesktopSshPasswordPromptCancellationError" as const;
+
+export const DesktopSshPasswordPromptCancellationReason = Schema.Literals([
+  "user-cancelled",
+  "window-closed",
+  "service-stopped",
+  "timed-out",
+]);
+export type DesktopSshPasswordPromptCancellationReason =
+  typeof DesktopSshPasswordPromptCancellationReason.Type;
 
-export const DesktopSshPasswordPromptCancelledResultSchema = Schema.Struct({
-  type: Schema.Literal(DesktopSshPasswordPromptCancelledType),
-  message: Schema.String,
-});
+export class DesktopSshPasswordPromptCancellationError extends Schema.TaggedErrorClass<DesktopSshPasswordPromptCancellationError>()(
+  DesktopSshPasswordPromptCancellationErrorTag,
+  {
+    reason: DesktopSshPasswordPromptCancellationReason,
+    requestId: Schema.String,
+    destination: Schema.String,
+    cause: Schema.Defect(),
+  },
+) {
+  override get message(): string {
+    return `SSH authentication did not complete for ${this.destination}.`;
+  }
+}
+
+export const isDesktopSshPasswordPromptCancellationError = Schema.is(
+  DesktopSshPasswordPromptCancellationError,
+);
 
 export const DesktopSshEnvironmentEnsureOptionsSchema = Schema.Struct({
   issuePairingToken: Schema.optionalKey(Schema.Boolean),
@@ -347,7 +370,7 @@ export const DesktopSshEnvironmentEnsureInputSchema = Schema.Struct({
 
 export const DesktopSshEnvironmentEnsureResultSchema = Schema.Union([
   DesktopSshEnvironmentBootstrapSchema,
-  DesktopSshPasswordPromptCancelledResultSchema,
+  DesktopSshPasswordPromptCancellationError,
 ]);
 
 export const DesktopSshHttpBaseUrlInputSchema = Schema.Struct({
@@ -919,6 +942,7 @@ export interface DesktopBridge {
     items: readonly ContextMenuItem<T>[],
     position?: { x: number; y: number },
   ) => Promise<T | null>;
+  /** Resolves false when the URL is unsafe or the desktop shell cannot open it. */
   openExternal: (url: string) => Promise<boolean>;
   onMenuAction: (listener: (action: string) => void) => () => void;
   getUpdateState: () => Promise<DesktopUpdateState>;
diff --git a/packages/contracts/src/keybindings.ts b/packages/contracts/src/keybindings.ts
index 4a5ffd0c3dd..c0e6eea7f0f 100644
--- a/packages/contracts/src/keybindings.ts
+++ b/packages/contracts/src/keybindings.ts
@@ -157,14 +157,21 @@ export const ResolvedKeybindingsConfig = Schema.Array(ResolvedKeybindingRule).ch
 export type ResolvedKeybindingsConfig = typeof ResolvedKeybindingsConfig.Type;
 
 export class KeybindingsConfigError extends Schema.TaggedErrorClass<KeybindingsConfigError>()(
-  "KeybindingsConfigParseError",
+  "KeybindingsConfigError",
   {
     configPath: Schema.String,
-    detail: Schema.String,
-    cause: Schema.optional(Schema.Defect()),
+    operation: Schema.Literals([
+      "access",
+      "read",
+      "decode",
+      "encode",
+      "write",
+      "prepare-directory",
+    ]),
+    cause: Schema.Defect(),
   },
 ) {
   override get message(): string {
-    return `Unable to parse keybindings config at ${this.configPath}: ${this.detail}`;
+    return `Keybindings config operation '${this.operation}' failed at ${this.configPath}.`;
   }
 }
diff --git a/packages/effect-acp/package.json b/packages/effect-acp/package.json
index 4455dd460e7..5ecd05009fb 100644
--- a/packages/effect-acp/package.json
+++ b/packages/effect-acp/package.json
@@ -38,6 +38,7 @@
     "generate": "node scripts/generate.ts"
   },
   "dependencies": {
+    "@t3tools/shared": "workspace:*",
     "effect": "catalog:"
   },
   "devDependencies": {
diff --git a/packages/effect-acp/scripts/generate.test.ts b/packages/effect-acp/scripts/generate.test.ts
new file mode 100644
index 00000000000..e11cb460ecf
--- /dev/null
+++ b/packages/effect-acp/scripts/generate.test.ts
@@ -0,0 +1,175 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { assert, describe, expect, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Schema from "effect/Schema";
+import * as Sink from "effect/Sink";
+import * as Stream from "effect/Stream";
+import { HttpClient, HttpClientResponse } from "effect/unstable/http";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+import * as Generator from "./generate.ts";
+
+const isDownloadError = Schema.is(Generator.AcpGeneratorDownloadError);
+const isDownloadFileError = Schema.is(Generator.AcpGeneratorDownloadFileError);
+const isDocumentDecodeError = Schema.is(Generator.AcpGeneratorDocumentDecodeError);
+const isFormatExitError = Schema.is(Generator.AcpGeneratorFormatExitError);
+const isSchemaNameParseError = Schema.is(Generator.AcpGeneratorSchemaNameParseError);
+const isSchemaValueDeclarationMissingError = Schema.is(
+  Generator.AcpGeneratorSchemaValueDeclarationMissingError,
+);
+
+const httpClient = (response: Response) =>
+  HttpClient.make((request) => Effect.succeed(HttpClientResponse.fromWeb(request, response)));
+
+function processHandle(exitCode: number) {
+  return ChildProcessSpawner.makeHandle({
+    pid: ChildProcessSpawner.ProcessId(1),
+    exitCode: Effect.succeed(ChildProcessSpawner.ExitCode(exitCode)),
+    isRunning: Effect.succeed(false),
+    kill: () => Effect.void,
+    unref: Effect.succeed(Effect.void),
+    stdin: Sink.drain,
+    stdout: Stream.empty,
+    stderr: Stream.empty,
+    all: Stream.empty,
+    getInputFd: () => Sink.drain,
+    getOutputFd: () => Stream.empty,
+  });
+}
+
+describe("ACP schema generator errors", () => {
+  it.effect("retains safe URL diagnostics, output path, and HTTP cause when a download fails", () =>
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const directory = yield* fs.makeTempDirectoryScoped({ prefix: "acp-generator-test-" });
+      const url =
+        "https://generator-user:generator-password@example.test/private/schema.json?token=generator-secret#fragment";
+      const outputPath = `${directory}/schema.json`;
+      const error = yield* Generator.downloadFile(url, outputPath).pipe(
+        Effect.provideService(
+          HttpClient.HttpClient,
+          httpClient(new Response("unavailable", { status: 503 })),
+        ),
+        Effect.flip,
+      );
+
+      assert(isDownloadError(error));
+      expect(error).toMatchObject({
+        urlInputLength: url.length,
+        urlProtocol: "https:",
+        urlHostname: "example.test",
+      });
+      expect(error).not.toHaveProperty("url");
+      expect(error.outputPath).toBe(outputPath);
+      expect(error.stage).toBe("request");
+      expect(error.cause).toBeDefined();
+      expect(error.message).toContain(outputPath);
+      const { cause: _, ...directDiagnostics } = error;
+      expect(directDiagnostics).not.toHaveProperty("url");
+      expect(directDiagnostics.urlProtocol).toBe("https:");
+      expect(directDiagnostics.urlHostname).toBe("example.test");
+      expect(error.message).not.toMatch(
+        /generator-user|generator-password|private|token|generator-secret|fragment/,
+      );
+    }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
+  );
+
+  it.effect("retains download context when the response cannot be written", () =>
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const outputPath = yield* fs.makeTempDirectoryScoped({ prefix: "acp-generator-test-" });
+      const url = "https://example.test/schema.json";
+      const error = yield* Generator.downloadFile(url, outputPath).pipe(
+        Effect.provideService(
+          HttpClient.HttpClient,
+          httpClient(new Response("{}", { status: 200 })),
+        ),
+        Effect.flip,
+      );
+
+      assert(isDownloadFileError(error));
+      expect(error).toMatchObject({
+        urlInputLength: url.length,
+        urlProtocol: "https:",
+        urlHostname: "example.test",
+      });
+      expect(error).not.toHaveProperty("url");
+      expect(error.outputPath).toBe(outputPath);
+      expect(error.stage).toBe("write-file");
+      expect(error.cause).toBeDefined();
+    }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
+  );
+
+  it.effect("adds source file context to upstream document decode failures", () =>
+    Effect.gen(function* () {
+      const schemaPath = "/tmp/upstream-schema.json";
+      const schemaError = yield* Generator.decodeUpstreamSchemaDocument(
+        "not-json",
+        schemaPath,
+      ).pipe(Effect.flip);
+      assert(isDocumentDecodeError(schemaError));
+      expect(schemaError.document).toBe("schema");
+      expect(schemaError.filePath).toBe(schemaPath);
+      expect(schemaError.cause).toBeDefined();
+
+      const metadataPath = "/tmp/upstream-meta.json";
+      const metadataError = yield* Generator.decodeMetaDocument("not-json", metadataPath).pipe(
+        Effect.flip,
+      );
+      assert(isDocumentDecodeError(metadataError));
+      expect(metadataError.document).toBe("metadata");
+      expect(metadataError.filePath).toBe(metadataPath);
+      expect(metadataError.cause).toBeDefined();
+    }),
+  );
+
+  it.effect("reports formatter commands and nonzero exit codes structurally", () => {
+    let spawned: ChildProcess.StandardCommand | undefined;
+    const spawner = ChildProcessSpawner.make((command) => {
+      if (ChildProcess.isStandardCommand(command)) {
+        spawned = command;
+      }
+      return Effect.succeed(processHandle(23));
+    });
+
+    return Effect.gen(function* () {
+      const generatedDir = "/tmp/acp-generated";
+      const error = yield* Generator.formatGeneratedFiles(generatedDir).pipe(Effect.flip);
+
+      assert(isFormatExitError(error));
+      expect(error.command).toBe("bun");
+      expect(error.argumentCount).toBe(2);
+      expect(error).not.toHaveProperty("args");
+      expect(error.generatedDir).toBe(generatedDir);
+      expect(error.exitCode).toBe(23);
+      expect(error.message).toContain("23");
+      expect(spawned?.command).toBe("bun");
+      expect(spawned?.args).toEqual(["oxfmt", generatedDir]);
+    }).pipe(Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner));
+  });
+
+  it.effect("returns malformed generated schema declarations as typed failures", () =>
+    Effect.gen(function* () {
+      const missingValueError = yield* Generator.collectSchemaEntries(
+        "export type Session = string;",
+      ).pipe(Effect.flip);
+      assert(isSchemaValueDeclarationMissingError(missingValueError));
+      expect(missingValueError).toMatchObject({
+        lineIndex: 0,
+        typeDeclarationLength: 29,
+        nextLinePresent: false,
+      });
+      expect(missingValueError).not.toHaveProperty("typeDeclaration");
+
+      const nameParseError = yield* Generator.collectSchemaEntries(
+        "export type @ = string;\nexport const invalid = Schema.String;",
+      ).pipe(Effect.flip);
+      assert(isSchemaNameParseError(nameParseError));
+      expect(nameParseError).toMatchObject({
+        lineIndex: 0,
+        typeDeclarationLength: 23,
+      });
+      expect(nameParseError).not.toHaveProperty("typeDeclaration");
+    }),
+  );
+});
diff --git a/packages/effect-acp/scripts/generate.ts b/packages/effect-acp/scripts/generate.ts
index 1fe8e2edf8a..de88d5640e3 100644
--- a/packages/effect-acp/scripts/generate.ts
+++ b/packages/effect-acp/scripts/generate.ts
@@ -3,6 +3,7 @@
 import * as NodeRuntime from "@effect/platform-node/NodeRuntime";
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { make as makeJsonSchemaGenerator } from "@effect/openapi-generator/JsonSchemaGenerator";
+import { getUrlDiagnostics } from "@t3tools/shared/urlDiagnostics";
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
 import * as Layer from "effect/Layer";
@@ -15,11 +16,6 @@ import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
 
 const CURRENT_SCHEMA_RELEASE = "v0.11.3";
 
-interface GenerateCommandError {
-  readonly _tag: "GenerateCommandError";
-  readonly message: string;
-}
-
 interface GeneratedPaths {
   readonly generatedDir: string;
   readonly upstreamSchemaPath: string;
@@ -28,6 +24,118 @@ interface GeneratedPaths {
   readonly metaOutputPath: string;
 }
 
+const urlDiagnosticsSchema = {
+  urlInputLength: Schema.Number,
+  urlProtocol: Schema.optionalKey(Schema.String),
+  urlHostname: Schema.optionalKey(Schema.String),
+};
+
+function urlDiagnosticFields(url: string) {
+  const diagnostics = getUrlDiagnostics(url);
+  return {
+    urlInputLength: diagnostics.inputLength,
+    ...(diagnostics.protocol === undefined ? {} : { urlProtocol: diagnostics.protocol }),
+    ...(diagnostics.hostname === undefined ? {} : { urlHostname: diagnostics.hostname }),
+  };
+}
+
+export class AcpGeneratorDownloadError extends Schema.TaggedErrorClass<AcpGeneratorDownloadError>()(
+  "AcpGeneratorDownloadError",
+  {
+    ...urlDiagnosticsSchema,
+    outputPath: Schema.String,
+    stage: Schema.Literals(["request", "read-response"]),
+    cause: Schema.Defect(),
+  },
+) {
+  override get message(): string {
+    const source = this.urlHostname === undefined ? "the configured source" : this.urlHostname;
+    return `Failed to download the ACP generator input from ${source} to ${this.outputPath} during ${this.stage}.`;
+  }
+}
+
+export class AcpGeneratorDownloadFileError extends Schema.TaggedErrorClass<AcpGeneratorDownloadFileError>()(
+  "AcpGeneratorDownloadFileError",
+  {
+    ...urlDiagnosticsSchema,
+    outputPath: Schema.String,
+    stage: Schema.Literals(["create-directory", "write-file"]),
+    cause: Schema.Defect(),
+  },
+) {
+  override get message(): string {
+    return `Failed to store the ACP generator download at ${this.outputPath} during ${this.stage}.`;
+  }
+}
+
+export class AcpGeneratorDocumentDecodeError extends Schema.TaggedErrorClass<AcpGeneratorDocumentDecodeError>()(
+  "AcpGeneratorDocumentDecodeError",
+  {
+    document: Schema.Literals(["schema", "metadata"]),
+    filePath: Schema.String,
+    cause: Schema.Defect(),
+  },
+) {
+  override get message(): string {
+    return `Failed to decode the upstream ACP ${this.document} document at ${this.filePath}.`;
+  }
+}
+
+export class AcpGeneratorFormatProcessError extends Schema.TaggedErrorClass<AcpGeneratorFormatProcessError>()(
+  "AcpGeneratorFormatProcessError",
+  {
+    stage: Schema.Literals(["spawn", "wait-for-exit"]),
+    command: Schema.String,
+    argumentCount: Schema.Number,
+    generatedDir: Schema.String,
+    cause: Schema.Defect(),
+  },
+) {
+  override get message(): string {
+    return `ACP generator formatting command ${this.command} failed during ${this.stage} for ${this.generatedDir}.`;
+  }
+}
+
+export class AcpGeneratorFormatExitError extends Schema.TaggedErrorClass<AcpGeneratorFormatExitError>()(
+  "AcpGeneratorFormatExitError",
+  {
+    command: Schema.String,
+    argumentCount: Schema.Number,
+    generatedDir: Schema.String,
+    exitCode: Schema.Number,
+  },
+) {
+  override get message(): string {
+    return `ACP generator formatting command ${this.command} exited with code ${this.exitCode} for ${this.generatedDir}.`;
+  }
+}
+
+export class AcpGeneratorSchemaValueDeclarationMissingError extends Schema.TaggedErrorClass<AcpGeneratorSchemaValueDeclarationMissingError>()(
+  "AcpGeneratorSchemaValueDeclarationMissingError",
+  {
+    lineIndex: Schema.Number,
+    typeDeclarationLength: Schema.Number,
+    nextLinePresent: Schema.Boolean,
+    nextLineLength: Schema.optional(Schema.Number),
+  },
+) {
+  override get message(): string {
+    return `Generated ACP schema type declaration at line ${this.lineIndex + 1} has no following value declaration.`;
+  }
+}
+
+export class AcpGeneratorSchemaNameParseError extends Schema.TaggedErrorClass<AcpGeneratorSchemaNameParseError>()(
+  "AcpGeneratorSchemaNameParseError",
+  {
+    lineIndex: Schema.Number,
+    typeDeclarationLength: Schema.Number,
+  },
+) {
+  override get message(): string {
+    return `Could not extract an ACP schema name from generated declaration at line ${this.lineIndex + 1}.`;
+  }
+}
+
 const UpstreamJsonSchemaSchema = Schema.Struct({
   $defs: Schema.Record(Schema.String, Schema.Json),
 });
@@ -66,18 +174,57 @@ const ensureGeneratedDir = Effect.fn("ensureGeneratedDir")(function* () {
   yield* fs.makeDirectory(generatedDir, { recursive: true });
 });
 
-const downloadFile = Effect.fn("downloadFile")(function* (url: string, outputPath: string) {
+export const downloadFile = Effect.fn("downloadFile")(function* (url: string, outputPath: string) {
   const fs = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
 
-  yield* fs.makeDirectory(path.dirname(outputPath), { recursive: true });
+  yield* fs.makeDirectory(path.dirname(outputPath), { recursive: true }).pipe(
+    Effect.mapError(
+      (cause) =>
+        new AcpGeneratorDownloadFileError({
+          ...urlDiagnosticFields(url),
+          outputPath,
+          stage: "create-directory",
+          cause,
+        }),
+    ),
+  );
 
-  const text = yield* HttpClient.get(url).pipe(
+  const response = yield* HttpClient.get(url).pipe(
     Effect.flatMap(HttpClientResponse.filterStatusOk),
-    Effect.flatMap((response) => response.text),
+    Effect.mapError(
+      (cause) =>
+        new AcpGeneratorDownloadError({
+          ...urlDiagnosticFields(url),
+          outputPath,
+          stage: "request",
+          cause,
+        }),
+    ),
+  );
+  const text = yield* response.text.pipe(
+    Effect.mapError(
+      (cause) =>
+        new AcpGeneratorDownloadError({
+          ...urlDiagnosticFields(url),
+          outputPath,
+          stage: "read-response",
+          cause,
+        }),
+    ),
   );
 
-  yield* fs.writeFileString(outputPath, text);
+  yield* fs.writeFileString(outputPath, text).pipe(
+    Effect.mapError(
+      (cause) =>
+        new AcpGeneratorDownloadFileError({
+          ...urlDiagnosticFields(url),
+          outputPath,
+          stage: "write-file",
+          cause,
+        }),
+    ),
+  );
 });
 
 const downloadSchemas = Effect.fn("downloadSchemas")(function* (tag: string) {
@@ -85,14 +232,14 @@ const downloadSchemas = Effect.fn("downloadSchemas")(function* (tag: string) {
   const fs = yield* FileSystem.FileSystem;
   const baseUrl = `https://github.com/agentclientprotocol/agent-client-protocol/releases/download/${tag}`;
 
-  yield* downloadFile(`${baseUrl}/schema.unstable.json`, upstreamSchemaPath);
-  yield* downloadFile(`${baseUrl}/meta.unstable.json`, upstreamMetaPath);
-
   yield* Effect.addFinalizer(() =>
     Effect.all([fs.remove(upstreamSchemaPath), fs.remove(upstreamMetaPath)]).pipe(
       Effect.ignoreCause({ log: true }),
     ),
   );
+
+  yield* downloadFile(`${baseUrl}/schema.unstable.json`, upstreamSchemaPath);
+  yield* downloadFile(`${baseUrl}/meta.unstable.json`, upstreamMetaPath);
 });
 
 const readFileString = Effect.fn("readJsonFile")(function* (filePath: string) {
@@ -100,6 +247,69 @@ const readFileString = Effect.fn("readJsonFile")(function* (filePath: string) {
   return yield* fs.readFileString(filePath);
 });
 
+export const decodeUpstreamSchemaDocument = Effect.fn("decodeUpstreamSchemaDocument")(function* (
+  raw: string,
+  filePath: string,
+) {
+  return yield* decodeUpstreamSchema(raw).pipe(
+    Effect.mapError(
+      (cause) => new AcpGeneratorDocumentDecodeError({ document: "schema", filePath, cause }),
+    ),
+  );
+});
+
+export const decodeMetaDocument = Effect.fn("decodeMetaDocument")(function* (
+  raw: string,
+  filePath: string,
+) {
+  return yield* decodeMetaJson(raw).pipe(
+    Effect.mapError(
+      (cause) => new AcpGeneratorDocumentDecodeError({ document: "metadata", filePath, cause }),
+    ),
+  );
+});
+
+export const formatGeneratedFiles = Effect.fn("formatGeneratedFiles")(function* (
+  generatedDir: string,
+) {
+  const command = "bun";
+  const args = ["oxfmt", generatedDir];
+  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+  const child = yield* spawner.spawn(ChildProcess.make(command, args)).pipe(
+    Effect.mapError(
+      (cause) =>
+        new AcpGeneratorFormatProcessError({
+          stage: "spawn",
+          command,
+          argumentCount: args.length,
+          generatedDir,
+          cause,
+        }),
+    ),
+  );
+  const exitCode = yield* child.exitCode.pipe(
+    Effect.mapError(
+      (cause) =>
+        new AcpGeneratorFormatProcessError({
+          stage: "wait-for-exit",
+          command,
+          argumentCount: args.length,
+          generatedDir,
+          cause,
+        }),
+    ),
+  );
+
+  if (exitCode !== 0) {
+    return yield* new AcpGeneratorFormatExitError({
+      command,
+      argumentCount: args.length,
+      generatedDir,
+      exitCode,
+    });
+  }
+});
+
 const writeGeneratedFiles = Effect.fn("writeGeneratedFiles")(function* (
   schemaOutput: string,
   metaOutput: string,
@@ -111,9 +321,7 @@ const writeGeneratedFiles = Effect.fn("writeGeneratedFiles")(function* (
   yield* fs.writeFileString(metaOutputPath, metaOutput);
 });
 
-function collectSchemaEntries(
-  chunk: string,
-): ReadonlyArray<{ readonly name: string; readonly code: string }> {
+export const collectSchemaEntries = Effect.fn("collectSchemaEntries")(function* (chunk: string) {
   const lines = chunk
     .split("\n")
     .map((line) => line.trim())
@@ -128,12 +336,20 @@ function collectSchemaEntries(
 
     const constLine = lines[index + 1];
     if (!constLine?.startsWith("export const ")) {
-      throw new Error(`Malformed generator output near: ${typeLine}`);
+      return yield* new AcpGeneratorSchemaValueDeclarationMissingError({
+        lineIndex: index,
+        typeDeclarationLength: typeLine.length,
+        nextLinePresent: constLine !== undefined,
+        ...(constLine === undefined ? {} : { nextLineLength: constLine.length }),
+      });
     }
 
     const match = /^export type ([A-Za-z0-9_]+)/.exec(typeLine);
     if (!match?.[1]) {
-      throw new Error(`Could not extract schema name from: ${typeLine}`);
+      return yield* new AcpGeneratorSchemaNameParseError({
+        lineIndex: index,
+        typeDeclarationLength: typeLine.length,
+      });
     }
 
     entries.push({
@@ -144,7 +360,7 @@ function collectSchemaEntries(
   }
 
   return entries;
-}
+});
 
 function normalizeNullableTypes(value: Schema.Json): Schema.Json {
   if (Array.isArray(value)) {
@@ -204,10 +420,10 @@ const generateSchemas = Effect.fn("generateSchemas")(function* (skipDownload: bo
     yield* downloadSchemas(CURRENT_SCHEMA_RELEASE);
   }
 
-  const upstreamSchema = yield* readFileString(upstreamSchemaPath).pipe(
-    Effect.flatMap(decodeUpstreamSchema),
-  );
-  const upstreamMeta = yield* readFileString(upstreamMetaPath).pipe(Effect.flatMap(decodeMetaJson));
+  const upstreamSchemaRaw = yield* readFileString(upstreamSchemaPath);
+  const upstreamSchema = yield* decodeUpstreamSchemaDocument(upstreamSchemaRaw, upstreamSchemaPath);
+  const upstreamMetaRaw = yield* readFileString(upstreamMetaPath);
+  const upstreamMeta = yield* decodeMetaDocument(upstreamMetaRaw, upstreamMetaPath);
   const normalizedDefinitions = Object.fromEntries(
     Object.entries(upstreamSchema.$defs).map(([name, schema]) => [
       name,
@@ -227,7 +443,8 @@ const generateSchemas = Effect.fn("generateSchemas")(function* (skipDownload: bo
 
   const output = generator.generate("openapi-3.1", normalizedDefinitions as never, false).trim();
   if (output.length > 0) {
-    for (const entry of collectSchemaEntries(output)) {
+    const schemaEntries = yield* collectSchemaEntries(output);
+    for (const entry of schemaEntries) {
       if (!generatedEntries.has(entry.name)) {
         generatedEntries.set(entry.name, entry.code);
       }
@@ -264,18 +481,7 @@ const generateSchemas = Effect.fn("generateSchemas")(function* (skipDownload: bo
   );
 
   const { generatedDir } = yield* getGeneratedPaths();
-  yield* Effect.service(ChildProcessSpawner.ChildProcessSpawner).pipe(
-    Effect.flatMap((spawner) => spawner.spawn(ChildProcess.make("bun", ["oxfmt", generatedDir]))),
-    Effect.flatMap((child) => child.exitCode),
-    Effect.tap((code) =>
-      code === 0
-        ? Effect.void
-        : Effect.fail<GenerateCommandError>({
-            _tag: "GenerateCommandError",
-            message: `oxfmt failed with exit code ${code}`,
-          }),
-    ),
-  );
+  yield* formatGeneratedFiles(generatedDir);
 });
 
 const generateCommand = Command.make(
@@ -292,8 +498,10 @@ const runtimeLayer = Layer.mergeAll(
   FetchHttpClient.layer,
 );
 
-Command.run(generateCommand, { version: "0.0.0" }).pipe(
-  Effect.scoped,
-  Effect.provide(runtimeLayer),
-  NodeRuntime.runMain,
-);
+if (import.meta.main) {
+  Command.run(generateCommand, { version: "0.0.0" }).pipe(
+    Effect.scoped,
+    Effect.provide(runtimeLayer),
+    NodeRuntime.runMain,
+  );
+}
diff --git a/packages/effect-codex-app-server/package.json b/packages/effect-codex-app-server/package.json
index a067976c616..ea88887e7de 100644
--- a/packages/effect-codex-app-server/package.json
+++ b/packages/effect-codex-app-server/package.json
@@ -31,6 +31,7 @@
     "probe": "node test/examples/codex-app-server-probe.ts"
   },
   "dependencies": {
+    "@t3tools/shared": "workspace:*",
     "effect": "catalog:"
   },
   "devDependencies": {
diff --git a/packages/effect-codex-app-server/scripts/generate.test.ts b/packages/effect-codex-app-server/scripts/generate.test.ts
new file mode 100644
index 00000000000..ed9ee4bd194
--- /dev/null
+++ b/packages/effect-codex-app-server/scripts/generate.test.ts
@@ -0,0 +1,167 @@
+import { assert, describe, expect, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as Sink from "effect/Sink";
+import * as Stream from "effect/Stream";
+import { HttpClient, HttpClientResponse } from "effect/unstable/http";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+import * as Generator from "./generate.ts";
+
+const isGeneratorFetchError = Schema.is(Generator.GeneratorFetchError);
+const isGeneratorDirectoryDecodeError = Schema.is(Generator.GeneratorDirectoryDecodeError);
+const isGeneratorSchemaDocumentDecodeError = Schema.is(
+  Generator.GeneratorSchemaDocumentDecodeError,
+);
+const isGeneratorFormatExitError = Schema.is(Generator.GeneratorFormatExitError);
+const isGeneratorSchemaNameParseError = Schema.is(Generator.GeneratorSchemaNameParseError);
+const isGeneratorSchemaValueDeclarationMissingError = Schema.is(
+  Generator.GeneratorSchemaValueDeclarationMissingError,
+);
+
+const httpClient = (response: Response) =>
+  HttpClient.make((request) => Effect.succeed(HttpClientResponse.fromWeb(request, response)));
+
+function processHandle(exitCode: number) {
+  return ChildProcessSpawner.makeHandle({
+    pid: ChildProcessSpawner.ProcessId(1),
+    exitCode: Effect.succeed(ChildProcessSpawner.ExitCode(exitCode)),
+    isRunning: Effect.succeed(false),
+    kill: () => Effect.void,
+    unref: Effect.succeed(Effect.void),
+    stdin: Sink.drain,
+    stdout: Stream.empty,
+    stderr: Stream.empty,
+    all: Stream.empty,
+    getInputFd: () => Sink.drain,
+    getOutputFd: () => Stream.empty,
+  });
+}
+
+describe("Codex schema generator errors", () => {
+  it.effect("retains safe URL diagnostics and the HTTP cause when fetching fails", () =>
+    Effect.gen(function* () {
+      const url =
+        "https://generator-user:generator-password@example.test/private/schema.json?token=generator-secret#fragment";
+      const error = yield* Generator.fetchText(url).pipe(
+        Effect.provideService(
+          HttpClient.HttpClient,
+          httpClient(new Response("unavailable", { status: 503 })),
+        ),
+        Effect.flip,
+      );
+
+      assert(isGeneratorFetchError(error));
+      expect(error).toMatchObject({
+        urlInputLength: url.length,
+        urlProtocol: "https:",
+        urlHostname: "example.test",
+      });
+      expect(error).not.toHaveProperty("url");
+      expect(error.stage).toBe("request");
+      expect(error.cause).toBeDefined();
+      const { cause: _, ...directDiagnostics } = error;
+      expect(directDiagnostics).not.toHaveProperty("url");
+      expect(directDiagnostics.urlProtocol).toBe("https:");
+      expect(directDiagnostics.urlHostname).toBe("example.test");
+      expect(error.message).not.toMatch(
+        /generator-user|generator-password|private|token|generator-secret|fragment/,
+      );
+    }),
+  );
+
+  it.effect("adds the GitHub directory path to listing decode failures", () =>
+    Effect.gen(function* () {
+      const error = yield* Generator.fetchDirectoryEntries("schema/json/v2").pipe(
+        Effect.provideService(
+          HttpClient.HttpClient,
+          httpClient(new Response("not-json", { status: 200 })),
+        ),
+        Effect.flip,
+      );
+
+      assert(isGeneratorDirectoryDecodeError(error));
+      expect(error.directoryPath).toBe("schema/json/v2");
+      expect(error).toMatchObject({
+        urlProtocol: "https:",
+        urlHostname: "api.github.com",
+      });
+      expect(error.urlInputLength).toBeGreaterThan(0);
+      expect(error).not.toHaveProperty("url");
+      expect(error.cause).toBeDefined();
+      expect(error.message).toContain("schema/json/v2");
+    }),
+  );
+
+  it.effect("adds repository and download context to schema decode failures", () =>
+    Effect.gen(function* () {
+      const repositoryPath = "codex-rs/app-server-protocol/schema/json/v2/Thread.json";
+      const url = "https://raw.example.test/Thread.json";
+      const error = yield* Generator.decodeSchemaDocument({
+        repositoryPath,
+        url,
+        raw: "not-json",
+      }).pipe(Effect.flip);
+
+      assert(isGeneratorSchemaDocumentDecodeError(error));
+      expect(error.repositoryPath).toBe(repositoryPath);
+      expect(error).toMatchObject({
+        urlInputLength: url.length,
+        urlProtocol: "https:",
+        urlHostname: "raw.example.test",
+      });
+      expect(error).not.toHaveProperty("url");
+      expect(error.cause).toBeDefined();
+      expect(error.message).toContain(repositoryPath);
+    }),
+  );
+
+  it.effect("reports formatter commands and nonzero exit codes structurally", () => {
+    let spawned: ChildProcess.StandardCommand | undefined;
+    const spawner = ChildProcessSpawner.make((command) => {
+      if (ChildProcess.isStandardCommand(command)) {
+        spawned = command;
+      }
+      return Effect.succeed(processHandle(17));
+    });
+
+    return Effect.gen(function* () {
+      const generatedDir = "/tmp/codex-generated";
+      const error = yield* Generator.formatGeneratedFiles(generatedDir).pipe(Effect.flip);
+
+      assert(isGeneratorFormatExitError(error));
+      expect(error.command).toBe("vp");
+      expect(error.argumentCount).toBe(3);
+      expect(error).not.toHaveProperty("args");
+      expect(error.generatedDir).toBe(generatedDir);
+      expect(error.exitCode).toBe(17);
+      expect(error.message).toContain("17");
+      expect(spawned?.command).toBe("vp");
+      expect(spawned?.args).toEqual(["fmt", generatedDir, "--write"]);
+    }).pipe(Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner));
+  });
+
+  it.effect("returns malformed generated schema declarations as typed failures", () =>
+    Effect.gen(function* () {
+      const missingValueError = yield* Generator.collectSchemaEntries(
+        "export type Session = string;",
+      ).pipe(Effect.flip);
+      assert(isGeneratorSchemaValueDeclarationMissingError(missingValueError));
+      expect(missingValueError).toMatchObject({
+        lineIndex: 0,
+        typeDeclarationLength: 29,
+        nextLinePresent: false,
+      });
+      expect(missingValueError).not.toHaveProperty("typeDeclaration");
+
+      const nameParseError = yield* Generator.collectSchemaEntries(
+        "export type @ = string;\nexport const invalid = Schema.String;",
+      ).pipe(Effect.flip);
+      assert(isGeneratorSchemaNameParseError(nameParseError));
+      expect(nameParseError).toMatchObject({
+        lineIndex: 0,
+        typeDeclarationLength: 23,
+      });
+      expect(nameParseError).not.toHaveProperty("typeDeclaration");
+    }),
+  );
+});
diff --git a/packages/effect-codex-app-server/scripts/generate.ts b/packages/effect-codex-app-server/scripts/generate.ts
index 3deb4514292..20e2e581443 100644
--- a/packages/effect-codex-app-server/scripts/generate.ts
+++ b/packages/effect-codex-app-server/scripts/generate.ts
@@ -3,6 +3,7 @@
 import * as NodeRuntime from "@effect/platform-node/NodeRuntime";
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { make as makeJsonSchemaGenerator } from "@effect/openapi-generator/JsonSchemaGenerator";
+import { getUrlDiagnostics } from "@t3tools/shared/urlDiagnostics";
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
 import * as Layer from "effect/Layer";
@@ -59,14 +60,141 @@ interface JsonSchemaFile {
   readonly fileName: string;
   readonly downloadUrl: string;
   readonly qualifiedName: string;
+  readonly repositoryPath: string;
 }
 
-class GeneratorError extends Schema.TaggedErrorClass<GeneratorError>()("GeneratorError", {
-  detail: Schema.String,
-  cause: Schema.optional(Schema.Defect()),
-}) {
-  override get message() {
-    return this.detail;
+const urlDiagnosticsSchema = {
+  urlInputLength: Schema.Number,
+  urlProtocol: Schema.optionalKey(Schema.String),
+  urlHostname: Schema.optionalKey(Schema.String),
+};
+
+function urlDiagnosticFields(url: string) {
+  const diagnostics = getUrlDiagnostics(url);
+  return {
+    urlInputLength: diagnostics.inputLength,
+    ...(diagnostics.protocol === undefined ? {} : { urlProtocol: diagnostics.protocol }),
+    ...(diagnostics.hostname === undefined ? {} : { urlHostname: diagnostics.hostname }),
+  };
+}
+
+export class GeneratorFetchError extends Schema.TaggedErrorClass<GeneratorFetchError>()(
+  "GeneratorFetchError",
+  {
+    ...urlDiagnosticsSchema,
+    stage: Schema.Literals(["request", "read-response"]),
+    cause: Schema.Defect(),
+  },
+) {
+  override get message(): string {
+    const source = this.urlHostname === undefined ? "the configured source" : this.urlHostname;
+    return `Failed to fetch a Codex generator input from ${source} during ${this.stage}.`;
+  }
+}
+
+export class GeneratorDirectoryDecodeError extends Schema.TaggedErrorClass<GeneratorDirectoryDecodeError>()(
+  "GeneratorDirectoryDecodeError",
+  {
+    directoryPath: Schema.String,
+    ...urlDiagnosticsSchema,
+    cause: Schema.Defect(),
+  },
+) {
+  override get message(): string {
+    return `Failed to decode the GitHub directory listing for ${this.directoryPath}.`;
+  }
+}
+
+export class GeneratorSchemaDocumentDecodeError extends Schema.TaggedErrorClass<GeneratorSchemaDocumentDecodeError>()(
+  "GeneratorSchemaDocumentDecodeError",
+  {
+    repositoryPath: Schema.String,
+    ...urlDiagnosticsSchema,
+    cause: Schema.Defect(),
+  },
+) {
+  override get message(): string {
+    return `Failed to decode the Codex schema document ${this.repositoryPath}.`;
+  }
+}
+
+export class GeneratorFormatProcessError extends Schema.TaggedErrorClass<GeneratorFormatProcessError>()(
+  "GeneratorFormatProcessError",
+  {
+    operation: Schema.Literals(["spawn", "wait-for-exit"]),
+    command: Schema.String,
+    argumentCount: Schema.Number,
+    generatedDir: Schema.String,
+    cause: Schema.Defect(),
+  },
+) {
+  override get message(): string {
+    return `Generator formatting command ${this.command} failed during ${this.operation} for ${this.generatedDir}.`;
+  }
+}
+
+export class GeneratorFormatExitError extends Schema.TaggedErrorClass<GeneratorFormatExitError>()(
+  "GeneratorFormatExitError",
+  {
+    command: Schema.String,
+    argumentCount: Schema.Number,
+    generatedDir: Schema.String,
+    exitCode: Schema.Number,
+  },
+) {
+  override get message(): string {
+    return `Generator formatting command ${this.command} exited with code ${this.exitCode} for ${this.generatedDir}.`;
+  }
+}
+
+export class GeneratorSchemaValueDeclarationMissingError extends Schema.TaggedErrorClass<GeneratorSchemaValueDeclarationMissingError>()(
+  "GeneratorSchemaValueDeclarationMissingError",
+  {
+    lineIndex: Schema.Number,
+    typeDeclarationLength: Schema.Number,
+    nextLinePresent: Schema.Boolean,
+    nextLineLength: Schema.optional(Schema.Number),
+  },
+) {
+  override get message(): string {
+    return `Generated schema type declaration at line ${this.lineIndex + 1} has no following value declaration.`;
+  }
+}
+
+export class GeneratorSchemaNameParseError extends Schema.TaggedErrorClass<GeneratorSchemaNameParseError>()(
+  "GeneratorSchemaNameParseError",
+  {
+    lineIndex: Schema.Number,
+    typeDeclarationLength: Schema.Number,
+  },
+) {
+  override get message(): string {
+    return `Could not extract a schema name from generated declaration at line ${this.lineIndex + 1}.`;
+  }
+}
+
+export class GeneratorSchemaTypeResolutionError extends Schema.TaggedErrorClass<GeneratorSchemaTypeResolutionError>()(
+  "GeneratorSchemaTypeResolutionError",
+  {
+    rawTypeName: Schema.String,
+    candidates: Schema.Array(Schema.String),
+  },
+) {
+  override get message(): string {
+    return `Unable to resolve schema type ${this.rawTypeName}; tried ${this.candidates.join(", ")}.`;
+  }
+}
+
+export class GeneratorExternalReferenceResolutionError extends Schema.TaggedErrorClass<GeneratorExternalReferenceResolutionError>()(
+  "GeneratorExternalReferenceResolutionError",
+  {
+    reference: Schema.String,
+    currentNamespace: Schema.NullOr(Schema.String),
+    candidates: Schema.Array(Schema.String),
+  },
+) {
+  override get message(): string {
+    return `Unable to rewrite external reference ${this.reference} in namespace ${this.currentNamespace ?? "<root>"}; tried ${this.candidates.join(", ")}.`;
   }
 }
 
@@ -162,30 +290,108 @@ const ensureGeneratedDir = Effect.fn("ensureGeneratedDir")(function* () {
   yield* fs.makeDirectory(generatedDir, { recursive: true });
 });
 
-const fetchText = Effect.fn("fetchText")(function* (url: string) {
-  return yield* HttpClientRequest.get(url).pipe(
+export const fetchText = Effect.fn("fetchText")(function* (url: string) {
+  const response = yield* HttpClientRequest.get(url).pipe(
     HttpClientRequest.setHeader("user-agent", USER_AGENT),
     HttpClient.execute,
     Effect.flatMap(HttpClientResponse.filterStatusOk),
-    Effect.flatMap((okResponse) => okResponse.text),
     Effect.mapError(
       (cause) =>
-        new GeneratorError({
-          detail: `Failed to fetch ${url}`,
+        new GeneratorFetchError({
+          ...urlDiagnosticFields(url),
+          stage: "request",
+          cause,
+        }),
+    ),
+  );
+  return yield* response.text.pipe(
+    Effect.mapError(
+      (cause) =>
+        new GeneratorFetchError({
+          ...urlDiagnosticFields(url),
+          stage: "read-response",
           cause,
         }),
     ),
   );
 });
 
-const fetchDirectoryEntries = Effect.fn("fetchDirectoryEntries")(function* (path: string) {
-  const raw = yield* fetchText(`${GITHUB_API_BASE}/${path}?ref=${UPSTREAM_REF}`);
-  return yield* decodeGithubContentEntries(raw);
+export const fetchDirectoryEntries = Effect.fn("fetchDirectoryEntries")(function* (
+  directoryPath: string,
+) {
+  const url = `${GITHUB_API_BASE}/${directoryPath}?ref=${UPSTREAM_REF}`;
+  const raw = yield* fetchText(url);
+  return yield* decodeGithubContentEntries(raw).pipe(
+    Effect.mapError(
+      (cause) =>
+        new GeneratorDirectoryDecodeError({
+          directoryPath,
+          ...urlDiagnosticFields(url),
+          cause,
+        }),
+    ),
+  );
+});
+
+export const decodeSchemaDocument = Effect.fn("decodeSchemaDocument")(function* (input: {
+  readonly repositoryPath: string;
+  readonly url: string;
+  readonly raw: string;
+}) {
+  return yield* decodeJsonSchemaDocument(input.raw).pipe(
+    Effect.mapError(
+      (cause) =>
+        new GeneratorSchemaDocumentDecodeError({
+          repositoryPath: input.repositoryPath,
+          ...urlDiagnosticFields(input.url),
+          cause,
+        }),
+    ),
+  );
+});
+
+export const formatGeneratedFiles = Effect.fn("formatGeneratedFiles")(function* (
+  generatedDir: string,
+) {
+  const command = "vp";
+  const args = ["fmt", generatedDir, "--write"];
+  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+  const child = yield* spawner.spawn(ChildProcess.make(command, args)).pipe(
+    Effect.mapError(
+      (cause) =>
+        new GeneratorFormatProcessError({
+          operation: "spawn",
+          command,
+          argumentCount: args.length,
+          generatedDir,
+          cause,
+        }),
+    ),
+  );
+  const exitCode = yield* child.exitCode.pipe(
+    Effect.mapError(
+      (cause) =>
+        new GeneratorFormatProcessError({
+          operation: "wait-for-exit",
+          command,
+          argumentCount: args.length,
+          generatedDir,
+          cause,
+        }),
+    ),
+  );
+
+  if (exitCode !== 0) {
+    return yield* new GeneratorFormatExitError({
+      command,
+      argumentCount: args.length,
+      generatedDir,
+      exitCode,
+    });
+  }
 });
 
-function collectSchemaEntries(
-  chunk: string,
-): ReadonlyArray<{ readonly name: string; readonly code: string }> {
+export const collectSchemaEntries = Effect.fn("collectSchemaEntries")(function* (chunk: string) {
   const lines = chunk
     .split("\n")
     .map((line) => line.trim())
@@ -200,12 +406,20 @@ function collectSchemaEntries(
 
     const constLine = lines[index + 1];
     if (!constLine?.startsWith("export const ")) {
-      throw new Error(`Malformed generator output near: ${typeLine}`);
+      return yield* new GeneratorSchemaValueDeclarationMissingError({
+        lineIndex: index,
+        typeDeclarationLength: typeLine.length,
+        nextLinePresent: constLine !== undefined,
+        ...(constLine === undefined ? {} : { nextLineLength: constLine.length }),
+      });
     }
 
     const match = /^export type ([A-Za-z0-9_]+)/.exec(typeLine);
     if (!match?.[1]) {
-      throw new Error(`Could not extract schema name from: ${typeLine}`);
+      return yield* new GeneratorSchemaNameParseError({
+        lineIndex: index,
+        typeDeclarationLength: typeLine.length,
+      });
     }
 
     entries.push({
@@ -216,7 +430,7 @@ function collectSchemaEntries(
   }
 
   return entries;
-}
+});
 
 function normalizeNullableTypes(value: Schema.Json): Schema.Json {
   if (Array.isArray(value)) {
@@ -337,7 +551,7 @@ function resolveSchemaTypeName(
     }
   }
 
-  throw new Error(`Unable to resolve schema type name: ${rawTypeName}`);
+  throw new GeneratorSchemaTypeResolutionError({ rawTypeName, candidates });
 }
 
 function resolveResponseTypeName(
@@ -454,6 +668,7 @@ function buildJsonSchemaFiles(
           fileName: entry.name,
           downloadUrl: entry.download_url!,
           qualifiedName: relative.replace(/\.json$/, ""),
+          repositoryPath: entry.path,
         } satisfies JsonSchemaFile;
       }
       return {
@@ -461,6 +676,7 @@ function buildJsonSchemaFiles(
         fileName: entry.name,
         downloadUrl: entry.download_url!,
         qualifiedName: relative.replace(/\.json$/, ""),
+        repositoryPath: entry.path,
       } satisfies JsonSchemaFile;
     });
 }
@@ -504,7 +720,11 @@ function rewriteExternalRefs(
           .find((candidate) => candidate !== undefined);
 
         if (!rewritten) {
-          throw new Error(`Missing rewritten definition for ref: ${child}`);
+          throw new GeneratorExternalReferenceResolutionError({
+            reference: child,
+            currentNamespace: currentNamespace ?? null,
+            candidates,
+          });
         }
 
         return [key, `#/definitions/${rewritten}`];
@@ -545,7 +765,11 @@ const generateFiles = Effect.fn("generateFiles")(function* () {
 
   for (const file of jsonSchemaFiles) {
     const raw = yield* fetchText(file.downloadUrl);
-    const parsed = yield* decodeJsonSchemaDocument(raw);
+    const parsed = yield* decodeSchemaDocument({
+      repositoryPath: file.repositoryPath,
+      url: file.downloadUrl,
+      raw,
+    });
     const localDefinitionNames = new Map(
       Object.keys(parsed.definitions ?? {}).map((definitionName) => [
         definitionName,
@@ -601,7 +825,8 @@ const generateFiles = Effect.fn("generateFiles")(function* () {
   const generatedEntries = new Map<string, string>();
   const output = generator.generate("openapi-3.1", aggregateSchemas as never, false).trim();
   if (output.length > 0) {
-    for (const entry of collectSchemaEntries(output)) {
+    const schemaEntries = yield* collectSchemaEntries(output);
+    for (const entry of schemaEntries) {
       if (!generatedEntries.has(entry.name)) {
         generatedEntries.set(entry.name, entry.code);
       }
@@ -745,31 +970,19 @@ const generateFiles = Effect.fn("generateFiles")(function* () {
 
   yield* Effect.log(`Generated Codex App Server schemas from ${UPSTREAM_REF}`);
 
-  yield* Effect.service(ChildProcessSpawner.ChildProcessSpawner).pipe(
-    Effect.flatMap((spawner) =>
-      spawner.spawn(ChildProcess.make("vp", ["fmt", generatedDir, "--write"])),
-    ),
-    Effect.flatMap((child) => child.exitCode),
-    Effect.tap((code) =>
-      code === 0
-        ? Effect.void
-        : Effect.fail(
-            new GeneratorError({
-              detail: `vp fmt failed with exit code ${code}`,
-            }),
-          ),
-    ),
-  );
+  yield* formatGeneratedFiles(generatedDir);
 });
 
-generateFiles().pipe(
-  Effect.scoped,
-  Effect.provide(
-    Layer.mergeAll(
-      Logger.layer([Logger.consolePretty()]),
-      NodeServices.layer,
-      FetchHttpClient.layer,
+if (import.meta.main) {
+  generateFiles().pipe(
+    Effect.scoped,
+    Effect.provide(
+      Layer.mergeAll(
+        Logger.layer([Logger.consolePretty()]),
+        NodeServices.layer,
+        FetchHttpClient.layer,
+      ),
     ),
-  ),
-  NodeRuntime.runMain,
-);
+    NodeRuntime.runMain,
+  );
+}
diff --git a/packages/shared/package.json b/packages/shared/package.json
index 23705178bef..497a7e84f97 100644
--- a/packages/shared/package.json
+++ b/packages/shared/package.json
@@ -103,6 +103,10 @@
       "types": "./src/dpopCommon.ts",
       "import": "./src/dpopCommon.ts"
     },
+    "./urlDiagnostics": {
+      "types": "./src/urlDiagnostics.ts",
+      "import": "./src/urlDiagnostics.ts"
+    },
     "./relayAuth": {
       "types": "./src/relayAuth.ts",
       "import": "./src/relayAuth.ts"
diff --git a/packages/shared/src/advertisedEndpoint.test.ts b/packages/shared/src/advertisedEndpoint.test.ts
new file mode 100644
index 00000000000..8c336bfe286
--- /dev/null
+++ b/packages/shared/src/advertisedEndpoint.test.ts
@@ -0,0 +1,55 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import {
+  AdvertisedEndpointProtocolError,
+  AdvertisedEndpointUrlParseError,
+  normalizeHttpBaseUrl,
+} from "./advertisedEndpoint.ts";
+
+const captureError = (run: () => unknown): unknown => {
+  try {
+    run();
+  } catch (cause) {
+    return cause;
+  }
+  throw new Error("Expected operation to throw");
+};
+
+describe("advertised endpoints", () => {
+  it("normalizes websocket endpoints to an HTTP base URL", () => {
+    expect(normalizeHttpBaseUrl("wss://relay.example.com/path?query=value#fragment")).toBe(
+      "https://relay.example.com/",
+    );
+  });
+
+  it("preserves URL parser failures without retaining their raw input", () => {
+    const input = "not a URL";
+    const error = captureError(() => normalizeHttpBaseUrl(input));
+
+    expect(error).toBeInstanceOf(AdvertisedEndpointUrlParseError);
+    expect(error).toMatchObject({ inputLength: input.length });
+    expect(error).not.toHaveProperty("input");
+    expect((error as AdvertisedEndpointUrlParseError).cause).toBeInstanceOf(Error);
+    expect((error as Error).message).toBe("Invalid advertised endpoint URL.");
+  });
+
+  it("reports unsupported protocols without inventing a cause", () => {
+    const input =
+      "ftp://endpoint-user:endpoint-password@relay.example.com/private/path?token=secret#fragment";
+    const error = captureError(() => normalizeHttpBaseUrl(input));
+
+    expect(error).toBeInstanceOf(AdvertisedEndpointProtocolError);
+    expect(error).toMatchObject({
+      inputLength: input.length,
+      inputProtocol: "ftp:",
+      inputHostname: "relay.example.com",
+      protocol: "ftp:",
+    });
+    expect(error).not.toHaveProperty("input");
+    expect((error as Error & { cause?: unknown }).cause).toBeUndefined();
+    expect((error as Error).message).toBe("Endpoint must use HTTP or HTTPS. Received ftp:");
+    expect((error as Error).message).not.toContain("endpoint-password");
+    expect((error as Error).message).not.toContain("/private/path");
+    expect((error as Error).message).not.toContain("token=secret");
+  });
+});
diff --git a/packages/shared/src/advertisedEndpoint.ts b/packages/shared/src/advertisedEndpoint.ts
index 314d8272c81..9021aa739f4 100644
--- a/packages/shared/src/advertisedEndpoint.ts
+++ b/packages/shared/src/advertisedEndpoint.ts
@@ -6,6 +6,48 @@ import type {
   AdvertisedEndpointSource,
   AdvertisedEndpointStatus,
 } from "@t3tools/contracts";
+import * as Schema from "effect/Schema";
+
+import { getUrlDiagnostics } from "./urlDiagnostics.ts";
+
+const AdvertisedEndpointInputDiagnosticFields = {
+  inputLength: Schema.Number,
+  inputProtocol: Schema.optional(Schema.String),
+  inputHostname: Schema.optional(Schema.String),
+};
+
+function advertisedEndpointInputDiagnostics(input: string) {
+  const diagnostics = getUrlDiagnostics(input);
+  return {
+    inputLength: diagnostics.inputLength,
+    ...(diagnostics.protocol === undefined ? {} : { inputProtocol: diagnostics.protocol }),
+    ...(diagnostics.hostname === undefined ? {} : { inputHostname: diagnostics.hostname }),
+  };
+}
+
+export class AdvertisedEndpointUrlParseError extends Schema.TaggedErrorClass<AdvertisedEndpointUrlParseError>()(
+  "AdvertisedEndpointUrlParseError",
+  {
+    ...AdvertisedEndpointInputDiagnosticFields,
+    cause: Schema.Defect(),
+  },
+) {
+  override get message(): string {
+    return "Invalid advertised endpoint URL.";
+  }
+}
+
+export class AdvertisedEndpointProtocolError extends Schema.TaggedErrorClass<AdvertisedEndpointProtocolError>()(
+  "AdvertisedEndpointProtocolError",
+  {
+    ...AdvertisedEndpointInputDiagnosticFields,
+    protocol: Schema.String,
+  },
+) {
+  override get message(): string {
+    return `Endpoint must use HTTP or HTTPS. Received ${this.protocol}`;
+  }
+}
 
 export interface CreateAdvertisedEndpointInput {
   readonly id: string;
@@ -22,7 +64,15 @@ export interface CreateAdvertisedEndpointInput {
 }
 
 export function normalizeHttpBaseUrl(rawValue: string): string {
-  const url = new URL(rawValue);
+  let url: URL;
+  try {
+    url = new URL(rawValue);
+  } catch (cause) {
+    throw new AdvertisedEndpointUrlParseError({
+      ...advertisedEndpointInputDiagnostics(rawValue),
+      cause,
+    });
+  }
   if (url.protocol === "ws:") {
     url.protocol = "http:";
   } else if (url.protocol === "wss:") {
@@ -30,7 +80,10 @@ export function normalizeHttpBaseUrl(rawValue: string): string {
   }
 
   if (url.protocol !== "http:" && url.protocol !== "https:") {
-    throw new Error(`Endpoint must use HTTP or HTTPS. Received ${url.protocol}`);
+    throw new AdvertisedEndpointProtocolError({
+      ...advertisedEndpointInputDiagnostics(rawValue),
+      protocol: url.protocol,
+    });
   }
 
   url.pathname = "/";
diff --git a/packages/shared/src/dpop.test.ts b/packages/shared/src/dpop.test.ts
index c4ba298f66c..767a6ecf267 100644
--- a/packages/shared/src/dpop.test.ts
+++ b/packages/shared/src/dpop.test.ts
@@ -6,6 +6,7 @@ import {
   computeDpopAccessTokenHash,
   computeDpopJwkThumbprint,
   normalizeDpopHtu,
+  redactDpopRequestTarget,
   type DpopPublicJwk,
   verifyDpopProof,
 } from "./dpop.ts";
@@ -41,6 +42,18 @@ function signDpopProof(input: {
   return `${header}.${payload}.${signature}`;
 }
 
+describe("redactDpopRequestTarget", () => {
+  it("retains the scheme, host, port, and path while removing sensitive URL components", () => {
+    const url = "https://user:password@example.com:8443/oauth/token?code=secret#fragment";
+
+    assert.equal(redactDpopRequestTarget(url), "https://example.com:8443/oauth/token");
+  });
+
+  it("returns a safe sentinel for invalid input", () => {
+    assert.equal(redactDpopRequestTarget("not a URL?token=secret"), "<invalid-url>");
+  });
+});
+
 describe("verifyDpopProof", () => {
   const { privateKey, publicKey } = NodeCrypto.generateKeyPairSync("ec", {
     namedCurve: "P-256",
diff --git a/packages/shared/src/dpop.ts b/packages/shared/src/dpop.ts
index 88dcf8e3090..f2dd17516d0 100644
--- a/packages/shared/src/dpop.ts
+++ b/packages/shared/src/dpop.ts
@@ -88,6 +88,15 @@ export function normalizeDpopHtu(url: string): string | null {
   }
 }
 
+export function redactDpopRequestTarget(url: string): string {
+  try {
+    const parsed = new URL(url);
+    return `${parsed.protocol}//${parsed.host}${parsed.pathname}`;
+  } catch {
+    return "<invalid-url>";
+  }
+}
+
 export function computeDpopJwkThumbprint(jwk: DpopPublicJwk): string {
   return Encoding.encodeBase64Url(sha256(new TextEncoder().encode(dpopThumbprintInput(jwk))));
 }
diff --git a/packages/shared/src/urlDiagnostics.test.ts b/packages/shared/src/urlDiagnostics.test.ts
new file mode 100644
index 00000000000..b3ff378ee55
--- /dev/null
+++ b/packages/shared/src/urlDiagnostics.test.ts
@@ -0,0 +1,24 @@
+import { assert, describe, it } from "@effect/vitest";
+
+import { getUrlDiagnostics } from "./urlDiagnostics.ts";
+
+describe("getUrlDiagnostics", () => {
+  it("retains only input length, protocol, and hostname for valid URLs", () => {
+    const input =
+      "https://user:password@example.com:8443/private/path?access_token=secret#fragment";
+
+    assert.deepStrictEqual(getUrlDiagnostics(input), {
+      inputLength: input.length,
+      protocol: "https:",
+      hostname: "example.com",
+    });
+  });
+
+  it("returns only input length for invalid URLs", () => {
+    const input = "not a URL?access_token=secret";
+
+    assert.deepStrictEqual(getUrlDiagnostics(input), {
+      inputLength: input.length,
+    });
+  });
+});
diff --git a/packages/shared/src/urlDiagnostics.ts b/packages/shared/src/urlDiagnostics.ts
new file mode 100644
index 00000000000..6705e1ee7b4
--- /dev/null
+++ b/packages/shared/src/urlDiagnostics.ts
@@ -0,0 +1,19 @@
+export interface UrlDiagnostics {
+  readonly inputLength: number;
+  readonly protocol?: string;
+  readonly hostname?: string;
+}
+
+export function getUrlDiagnostics(input: string): UrlDiagnostics {
+  const inputLength = input.length;
+  try {
+    const url = new URL(input);
+    return {
+      inputLength,
+      protocol: url.protocol,
+      hostname: url.hostname,
+    };
+  } catch {
+    return { inputLength };
+  }
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 192723b7663..e9f8df16693 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -736,6 +736,9 @@ importers:
 
   packages/effect-acp:
     dependencies:
+      '@t3tools/shared':
+        specifier: workspace:*
+        version: link:../shared
       effect:
         specifier: 4.0.0-beta.78
         version: 4.0.0-beta.78(patch_hash=c502bc684210b707dfceb87d8fe6ad6843395af6e19cfc02cd65854898bde2c5)
@@ -758,6 +761,9 @@ importers:
 
   packages/effect-codex-app-server:
     dependencies:
+      '@t3tools/shared':
+        specifier: workspace:*
+        version: link:../shared
       effect:
         specifier: 4.0.0-beta.78
         version: 4.0.0-beta.78(patch_hash=c502bc684210b707dfceb87d8fe6ad6843395af6e19cfc02cd65854898bde2c5)
diff --git a/scripts/lib/update-manifest.ts b/scripts/lib/update-manifest.ts
index 191a3c0e535..894232f3e72 100644
--- a/scripts/lib/update-manifest.ts
+++ b/scripts/lib/update-manifest.ts
@@ -1,10 +1,138 @@
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+
+import { getUrlDiagnostics } from "@t3tools/shared/urlDiagnostics";
+
 export interface UpdateManifestFile {
   readonly url: string;
   readonly sha512: string;
   readonly size: number;
 }
 
-export type UpdateManifestScalar = string | number | boolean;
+export const UpdateManifestScalar = Schema.Union([Schema.String, Schema.Number, Schema.Boolean]);
+export type UpdateManifestScalar = typeof UpdateManifestScalar.Type;
+
+export const UpdateManifestScalarType = Schema.Literals(["string", "number", "boolean"]);
+export type UpdateManifestScalarType = typeof UpdateManifestScalarType.Type;
+
+export const UpdateManifestParseReason = Schema.Literals([
+  "incomplete file entry",
+  "sha512 without a file entry",
+  "size without a file entry",
+  "unsupported line",
+  "version must be a string",
+  "releaseDate must be a string",
+  "missing version",
+  "missing releaseDate",
+  "missing files",
+]);
+export type UpdateManifestParseReason = typeof UpdateManifestParseReason.Type;
+
+export class UpdateManifestParseError extends Schema.TaggedErrorClass<UpdateManifestParseError>()(
+  "UpdateManifestParseError",
+  {
+    platformLabel: Schema.String,
+    sourcePath: Schema.String,
+    lineNumber: Schema.optionalKey(Schema.Number),
+    reason: UpdateManifestParseReason,
+    lineLength: Schema.optionalKey(Schema.Number),
+  },
+) {
+  override get message(): string {
+    const location =
+      this.lineNumber === undefined ? this.sourcePath : `${this.sourcePath}:${this.lineNumber}`;
+    const input = this.lineLength === undefined ? "" : ` Input length: ${this.lineLength}.`;
+    return `Invalid ${this.platformLabel} update manifest at ${location}: ${this.reason}.${input}`;
+  }
+}
+
+export class UpdateManifestVersionConflictError extends Schema.TaggedErrorClass<UpdateManifestVersionConflictError>()(
+  "UpdateManifestVersionConflictError",
+  {
+    platformLabel: Schema.String,
+    primaryVersion: Schema.String,
+    secondaryVersion: Schema.String,
+  },
+) {
+  override get message(): string {
+    return `Cannot merge ${this.platformLabel} update manifests with different versions (${this.primaryVersion} vs ${this.secondaryVersion}).`;
+  }
+}
+
+export class UpdateManifestExtraConflictError extends Schema.TaggedErrorClass<UpdateManifestExtraConflictError>()(
+  "UpdateManifestExtraConflictError",
+  {
+    platformLabel: Schema.String,
+    key: Schema.String,
+    primaryValueType: UpdateManifestScalarType,
+    primaryValueLength: Schema.optionalKey(Schema.Number),
+    secondaryValueType: UpdateManifestScalarType,
+    secondaryValueLength: Schema.optionalKey(Schema.Number),
+  },
+) {
+  override get message(): string {
+    return `Cannot merge ${this.platformLabel} update manifests: conflicting '${this.key}' ${this.primaryValueType} and ${this.secondaryValueType} values.`;
+  }
+}
+
+export class UpdateManifestFileConflictError extends Schema.TaggedErrorClass<UpdateManifestFileConflictError>()(
+  "UpdateManifestFileConflictError",
+  {
+    platformLabel: Schema.String,
+    urlInputLength: Schema.Number,
+    urlProtocol: Schema.optionalKey(Schema.String),
+    urlHostname: Schema.optionalKey(Schema.String),
+    existingManifest: Schema.Literals(["primary", "secondary"]),
+    existingSha512Length: Schema.Number,
+    existingSize: Schema.Number,
+    conflictingManifest: Schema.Literals(["primary", "secondary"]),
+    conflictingSha512Length: Schema.Number,
+    conflictingSize: Schema.Number,
+    sha512Conflict: Schema.Boolean,
+    sizeConflict: Schema.Boolean,
+  },
+) {
+  override get message(): string {
+    const origin =
+      this.urlProtocol === undefined || this.urlHostname === undefined
+        ? ""
+        : ` at ${this.urlProtocol}//${this.urlHostname}`;
+    return `Cannot merge ${this.platformLabel} update manifests: conflicting file entry${origin} (URL input length: ${this.urlInputLength}).`;
+  }
+}
+
+export class UpdateManifestSerializationError extends Schema.TaggedErrorClass<UpdateManifestSerializationError>()(
+  "UpdateManifestSerializationError",
+  {
+    platformLabel: Schema.String,
+    key: Schema.String,
+  },
+) {
+  override get message(): string {
+    return `Cannot serialize ${this.platformLabel} update manifest: missing value for '${this.key}'.`;
+  }
+}
+
+export const UpdateManifestError = Schema.Union([
+  UpdateManifestParseError,
+  UpdateManifestVersionConflictError,
+  UpdateManifestExtraConflictError,
+  UpdateManifestFileConflictError,
+  UpdateManifestSerializationError,
+]);
+export type UpdateManifestError = typeof UpdateManifestError.Type;
+export const isUpdateManifestError = Schema.is(UpdateManifestError);
+
+export const attemptUpdateManifest = <A>(
+  evaluate: () => A,
+): Effect.Effect<A, UpdateManifestError> =>
+  Effect.suspend(() => {
+    try {
+      return Effect.succeed(evaluate());
+    } catch (error) {
+      return isUpdateManifestError(error) ? Effect.fail(error) : Effect.die(error);
+    }
+  });
 
 export interface UpdateManifest {
   readonly version: string;
@@ -40,9 +168,12 @@ function parseFileRecord(
     typeof currentFile.sha512 !== "string" ||
     typeof currentFile.size !== "number"
   ) {
-    throw new Error(
-      `Invalid ${platformLabel} update manifest at ${sourcePath}:${lineNumber}: incomplete file entry.`,
-    );
+    throw new UpdateManifestParseError({
+      platformLabel,
+      sourcePath,
+      lineNumber,
+      reason: "incomplete file entry",
+    });
   }
   return {
     url: currentFile.url,
@@ -94,9 +225,12 @@ export function parseUpdateManifest(
     const fileShaMatch = line.match(/^    sha512:\s*(.+)$/);
     if (fileShaMatch?.[1]) {
       if (currentFile === null) {
-        throw new Error(
-          `Invalid ${platformLabel} update manifest at ${sourcePath}:${lineNumber}: sha512 without a file entry.`,
-        );
+        throw new UpdateManifestParseError({
+          platformLabel,
+          sourcePath,
+          lineNumber,
+          reason: "sha512 without a file entry",
+        });
       }
       currentFile.sha512 = stripSingleQuotes(fileShaMatch[1].trim());
       continue;
@@ -105,9 +239,12 @@ export function parseUpdateManifest(
     const fileSizeMatch = line.match(/^    size:\s*(\d+)$/);
     if (fileSizeMatch?.[1]) {
       if (currentFile === null) {
-        throw new Error(
-          `Invalid ${platformLabel} update manifest at ${sourcePath}:${lineNumber}: size without a file entry.`,
-        );
+        throw new UpdateManifestParseError({
+          platformLabel,
+          sourcePath,
+          lineNumber,
+          reason: "size without a file entry",
+        });
       }
       currentFile.size = Number(fileSizeMatch[1]);
       continue;
@@ -127,9 +264,13 @@ export function parseUpdateManifest(
 
     const topLevelMatch = line.match(/^([A-Za-z][A-Za-z0-9]*):\s*(.+)$/);
     if (!topLevelMatch?.[1] || topLevelMatch[2] === undefined) {
-      throw new Error(
-        `Invalid ${platformLabel} update manifest at ${sourcePath}:${lineNumber}: unsupported line '${line}'.`,
-      );
+      throw new UpdateManifestParseError({
+        platformLabel,
+        sourcePath,
+        lineNumber,
+        reason: "unsupported line",
+        lineLength: line.length,
+      });
     }
 
     const [, key, rawValue] = topLevelMatch;
@@ -137,9 +278,12 @@ export function parseUpdateManifest(
 
     if (key === "version") {
       if (typeof value !== "string") {
-        throw new Error(
-          `Invalid ${platformLabel} update manifest at ${sourcePath}:${lineNumber}: version must be a string.`,
-        );
+        throw new UpdateManifestParseError({
+          platformLabel,
+          sourcePath,
+          lineNumber,
+          reason: "version must be a string",
+        });
       }
       version = value;
       continue;
@@ -147,9 +291,12 @@ export function parseUpdateManifest(
 
     if (key === "releaseDate") {
       if (typeof value !== "string") {
-        throw new Error(
-          `Invalid ${platformLabel} update manifest at ${sourcePath}:${lineNumber}: releaseDate must be a string.`,
-        );
+        throw new UpdateManifestParseError({
+          platformLabel,
+          sourcePath,
+          lineNumber,
+          reason: "releaseDate must be a string",
+        });
       }
       releaseDate = value;
       continue;
@@ -166,15 +313,25 @@ export function parseUpdateManifest(
   if (finalized) files.push(finalized);
 
   if (!version) {
-    throw new Error(`Invalid ${platformLabel} update manifest at ${sourcePath}: missing version.`);
+    throw new UpdateManifestParseError({
+      platformLabel,
+      sourcePath,
+      reason: "missing version",
+    });
   }
   if (!releaseDate) {
-    throw new Error(
-      `Invalid ${platformLabel} update manifest at ${sourcePath}: missing releaseDate.`,
-    );
+    throw new UpdateManifestParseError({
+      platformLabel,
+      sourcePath,
+      reason: "missing releaseDate",
+    });
   }
   if (files.length === 0) {
-    throw new Error(`Invalid ${platformLabel} update manifest at ${sourcePath}: missing files.`);
+    throw new UpdateManifestParseError({
+      platformLabel,
+      sourcePath,
+      reason: "missing files",
+    });
   }
 
   return {
@@ -185,6 +342,12 @@ export function parseUpdateManifest(
   };
 }
 
+function getScalarType(value: UpdateManifestScalar): UpdateManifestScalarType {
+  if (typeof value === "string") return "string";
+  if (typeof value === "number") return "number";
+  return "boolean";
+}
+
 function mergeExtras(
   primary: Readonly<Record<string, UpdateManifestScalar>>,
   secondary: Readonly<Record<string, UpdateManifestScalar>>,
@@ -195,9 +358,14 @@ function mergeExtras(
   for (const [key, value] of Object.entries(secondary)) {
     const existing = merged[key];
     if (existing !== undefined && existing !== value) {
-      throw new Error(
-        `Cannot merge ${platformLabel} update manifests: conflicting '${key}' values ('${existing}' vs '${value}').`,
-      );
+      throw new UpdateManifestExtraConflictError({
+        platformLabel,
+        key,
+        primaryValueType: getScalarType(existing),
+        ...(typeof existing === "string" ? { primaryValueLength: existing.length } : {}),
+        secondaryValueType: getScalarType(value),
+        ...(typeof value === "string" ? { secondaryValueLength: value.length } : {}),
+      });
     }
     merged[key] = value;
   }
@@ -211,27 +379,53 @@ export function mergeUpdateManifests(
   platformLabel: string,
 ): UpdateManifest {
   if (primary.version !== secondary.version) {
-    throw new Error(
-      `Cannot merge ${platformLabel} update manifests with different versions (${primary.version} vs ${secondary.version}).`,
-    );
+    throw new UpdateManifestVersionConflictError({
+      platformLabel,
+      primaryVersion: primary.version,
+      secondaryVersion: secondary.version,
+    });
   }
 
-  const filesByUrl = new Map<string, UpdateManifestFile>();
-  for (const file of [...primary.files, ...secondary.files]) {
-    const existing = filesByUrl.get(file.url);
-    if (existing && (existing.sha512 !== file.sha512 || existing.size !== file.size)) {
-      throw new Error(
-        `Cannot merge ${platformLabel} update manifests: conflicting file entry for ${file.url}.`,
-      );
+  const filesByUrl = new Map<
+    string,
+    { readonly manifest: "primary" | "secondary"; readonly file: UpdateManifestFile }
+  >();
+  for (const [manifest, files] of [
+    ["primary", primary.files],
+    ["secondary", secondary.files],
+  ] as const) {
+    for (const file of files) {
+      const existing = filesByUrl.get(file.url);
+      if (existing && (existing.file.sha512 !== file.sha512 || existing.file.size !== file.size)) {
+        const urlDiagnostics = getUrlDiagnostics(file.url);
+        throw new UpdateManifestFileConflictError({
+          platformLabel,
+          urlInputLength: urlDiagnostics.inputLength,
+          ...(urlDiagnostics.protocol === undefined
+            ? {}
+            : { urlProtocol: urlDiagnostics.protocol }),
+          ...(urlDiagnostics.hostname === undefined
+            ? {}
+            : { urlHostname: urlDiagnostics.hostname }),
+          existingManifest: existing.manifest,
+          existingSha512Length: existing.file.sha512.length,
+          existingSize: existing.file.size,
+          conflictingManifest: manifest,
+          conflictingSha512Length: file.sha512.length,
+          conflictingSize: file.size,
+          sha512Conflict: existing.file.sha512 !== file.sha512,
+          sizeConflict: existing.file.size !== file.size,
+        });
+      }
+      filesByUrl.set(file.url, { manifest, file });
     }
-    filesByUrl.set(file.url, file);
   }
 
   return {
     version: primary.version,
     releaseDate:
       primary.releaseDate >= secondary.releaseDate ? primary.releaseDate : secondary.releaseDate,
-    files: [...filesByUrl.values()],
+    files: [...filesByUrl.values()].map(({ file }) => file),
     extras: mergeExtras(primary.extras, secondary.extras, platformLabel),
   };
 }
@@ -264,9 +458,10 @@ export function serializeUpdateManifest(
   for (const key of Object.keys(manifest.extras).toSorted()) {
     const value = manifest.extras[key];
     if (value === undefined) {
-      throw new Error(
-        `Cannot serialize ${options.platformLabel} update manifest: missing value for '${key}'.`,
-      );
+      throw new UpdateManifestSerializationError({
+        platformLabel: options.platformLabel,
+        key,
+      });
     }
     lines.push(`${key}: ${serializeScalarValue(value)}`);
   }
diff --git a/scripts/merge-update-manifests.test.ts b/scripts/merge-update-manifests.test.ts
index 32431b81d33..afa1c027e0a 100644
--- a/scripts/merge-update-manifests.test.ts
+++ b/scripts/merge-update-manifests.test.ts
@@ -6,14 +6,27 @@ import * as Path from "effect/Path";
 import { Command, CliError } from "effect/unstable/cli";
 
 import {
+  mergeUpdateManifestFiles,
   mergePlatformUpdateManifests,
   mergeUpdateManifestsCommand,
   parsePlatformUpdateManifest,
   serializePlatformUpdateManifest,
 } from "./merge-update-manifests.ts";
+import { isUpdateManifestError, type UpdateManifestError } from "./lib/update-manifest.ts";
 
 const runCli = Command.runWith(mergeUpdateManifestsCommand, { version: "0.0.0" });
 
+function captureUpdateManifestError(run: () => unknown): UpdateManifestError {
+  let caught: unknown;
+  try {
+    run();
+  } catch (error) {
+    caught = error;
+  }
+  assert.ok(isUpdateManifestError(caught));
+  return caught;
+}
+
 describe("merge-update-manifests", () => {
   it("merges arm64 and x64 macOS update manifests into one multi-arch manifest", () => {
     const arm64 = parsePlatformUpdateManifest(
@@ -148,10 +161,121 @@ releaseDate: '2026-03-07T10:36:07.540Z'
       "latest-win-x64.yml",
     );
 
-    assert.throws(
-      () => mergePlatformUpdateManifests("win", primary, secondary),
-      /different versions/,
+    const error = captureUpdateManifestError(() =>
+      mergePlatformUpdateManifests("win", primary, secondary),
+    );
+    assert.equal(error._tag, "UpdateManifestVersionConflictError");
+    if (error._tag === "UpdateManifestVersionConflictError") {
+      assert.equal(error.platformLabel, "Windows");
+      assert.equal(error.primaryVersion, "0.0.4");
+      assert.equal(error.secondaryVersion, "0.0.5");
+    }
+  });
+
+  it("reports manifest parse location without retaining the unsupported input", () => {
+    const unsupportedLine = "authorization Bearer secret-token without-separator";
+    const error = captureUpdateManifestError(() =>
+      parsePlatformUpdateManifest("mac", unsupportedLine, "latest-mac.yml"),
+    );
+    assert.equal(error._tag, "UpdateManifestParseError");
+    if (error._tag === "UpdateManifestParseError") {
+      assert.equal(error.platformLabel, "macOS");
+      assert.equal(error.sourcePath, "latest-mac.yml");
+      assert.equal(error.lineNumber, 1);
+      assert.equal(error.reason, "unsupported line");
+      assert.equal(error.lineLength, unsupportedLine.length);
+      assert.notProperty(error, "offendingLine");
+      assert.equal(
+        error.message,
+        `Invalid macOS update manifest at latest-mac.yml:1: unsupported line. Input length: ${unsupportedLine.length}.`,
+      );
+      assert.notInclude(error.message, "Bearer");
+      assert.notInclude(error.message, "secret-token");
+    }
+  });
+
+  it("identifies both sources when duplicate primary file entries conflict", () => {
+    const privateUrl =
+      "https://user:password@example.test/releases/private/app.exe?token=secret-token#fragment";
+    const firstSha512 = "first-private-sha";
+    const secondSha512 = "second-private-sha";
+    const manifest = {
+      version: "1.0.0",
+      releaseDate: "2026-06-20T00:00:00.000Z",
+      extras: {},
+    };
+    const error = captureUpdateManifestError(() =>
+      mergePlatformUpdateManifests(
+        "win",
+        {
+          ...manifest,
+          files: [
+            { url: privateUrl, sha512: firstSha512, size: 1 },
+            { url: privateUrl, sha512: secondSha512, size: 2 },
+          ],
+        },
+        { ...manifest, files: [] },
+      ),
+    );
+
+    assert.equal(error._tag, "UpdateManifestFileConflictError");
+    if (error._tag === "UpdateManifestFileConflictError") {
+      assert.equal(error.existingManifest, "primary");
+      assert.equal(error.conflictingManifest, "primary");
+      assert.equal(error.urlInputLength, privateUrl.length);
+      assert.equal(error.urlProtocol, "https:");
+      assert.equal(error.urlHostname, "example.test");
+      assert.equal(error.existingSha512Length, firstSha512.length);
+      assert.equal(error.existingSize, 1);
+      assert.equal(error.conflictingSha512Length, secondSha512.length);
+      assert.equal(error.conflictingSize, 2);
+      assert.isTrue(error.sha512Conflict);
+      assert.isTrue(error.sizeConflict);
+      assert.notProperty(error, "url");
+      assert.notProperty(error, "existingSha512");
+      assert.notProperty(error, "conflictingSha512");
+
+      const diagnostics = [error.message, ...Object.values(error).map(String)].join("\n");
+      assert.notInclude(diagnostics, "user");
+      assert.notInclude(diagnostics, "password");
+      assert.notInclude(diagnostics, "/releases/private/app.exe");
+      assert.notInclude(diagnostics, "secret-token");
+      assert.notInclude(diagnostics, firstSha512);
+      assert.notInclude(diagnostics, secondSha512);
+    }
+  });
+
+  it("reports extra conflicts without retaining arbitrary scalar values", () => {
+    const primaryValue = "primary-private-value";
+    const secondaryValue = "secondary-private-value";
+    const manifest = {
+      version: "1.0.0",
+      releaseDate: "2026-06-20T00:00:00.000Z",
+      files: [{ url: "app.exe", sha512: "sha", size: 1 }],
+    };
+
+    const error = captureUpdateManifestError(() =>
+      mergePlatformUpdateManifests(
+        "win",
+        { ...manifest, extras: { releaseNotes: primaryValue } },
+        { ...manifest, extras: { releaseNotes: secondaryValue } },
+      ),
     );
+
+    assert.equal(error._tag, "UpdateManifestExtraConflictError");
+    if (error._tag === "UpdateManifestExtraConflictError") {
+      assert.equal(error.key, "releaseNotes");
+      assert.equal(error.primaryValueType, "string");
+      assert.equal(error.primaryValueLength, primaryValue.length);
+      assert.equal(error.secondaryValueType, "string");
+      assert.equal(error.secondaryValueLength, secondaryValue.length);
+      assert.notProperty(error, "primaryValue");
+      assert.notProperty(error, "secondaryValue");
+
+      const diagnostics = [error.message, ...Object.values(error).map(String)].join("\n");
+      assert.notInclude(diagnostics, primaryValue);
+      assert.notInclude(diagnostics, secondaryValue);
+    }
   });
 
   it("preserves quoted scalars as strings", () => {
@@ -286,6 +410,35 @@ releaseDate: '2026-03-07T10:36:07.540Z'
     }),
   );
 
+  it.effect("surfaces manifest validation as a typed failure", () =>
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const baseDir = yield* fs.makeTempDirectoryScoped({
+        prefix: "merge-update-manifests-invalid-",
+      });
+      const primaryPath = path.join(baseDir, "latest-mac.yml");
+      const secondaryPath = path.join(baseDir, "latest-mac-x64.yml");
+
+      yield* fs.writeFileString(primaryPath, "not yaml");
+      yield* fs.writeFileString(secondaryPath, arm64MacManifest);
+
+      const error = yield* mergeUpdateManifestFiles(
+        "mac",
+        primaryPath,
+        secondaryPath,
+        undefined,
+      ).pipe(Effect.flip);
+
+      assert.ok(isUpdateManifestError(error));
+      assert.equal(error._tag, "UpdateManifestParseError");
+      if (error._tag === "UpdateManifestParseError") {
+        assert.equal(error.sourcePath, primaryPath);
+        assert.equal(error.reason, "unsupported line");
+      }
+    }),
+  );
+
   it.effect("rejects invalid platform values during cli parsing", () =>
     Effect.gen(function* () {
       const error = yield* runCli(["--platform", "linux", "a.yml", "b.yml"]).pipe(Effect.flip);
diff --git a/scripts/merge-update-manifests.ts b/scripts/merge-update-manifests.ts
index f7ba30f8a30..f20d4dec6e4 100644
--- a/scripts/merge-update-manifests.ts
+++ b/scripts/merge-update-manifests.ts
@@ -10,6 +10,7 @@ import * as Schema from "effect/Schema";
 import { Argument, Command, Flag } from "effect/unstable/cli";
 
 import {
+  attemptUpdateManifest,
   mergeUpdateManifests,
   parseUpdateManifest,
   serializeUpdateManifest,
@@ -61,19 +62,22 @@ export const mergeUpdateManifestFiles = Effect.fn("mergeUpdateManifestFiles")(fu
   const secondaryPath = path.resolve(secondaryPathArg);
   const outputPath = path.resolve(outputPathArg ?? primaryPathArg);
 
-  const primaryManifest = parsePlatformUpdateManifest(
-    platform,
-    yield* fs.readFileString(primaryPath),
-    primaryPath,
+  const primaryRaw = yield* fs.readFileString(primaryPath);
+  const primaryManifest = yield* attemptUpdateManifest(() =>
+    parsePlatformUpdateManifest(platform, primaryRaw, primaryPath),
   );
-  const secondaryManifest = parsePlatformUpdateManifest(
-    platform,
-    yield* fs.readFileString(secondaryPath),
-    secondaryPath,
+  const secondaryRaw = yield* fs.readFileString(secondaryPath);
+  const secondaryManifest = yield* attemptUpdateManifest(() =>
+    parsePlatformUpdateManifest(platform, secondaryRaw, secondaryPath),
+  );
+  const merged = yield* attemptUpdateManifest(() =>
+    mergePlatformUpdateManifests(platform, primaryManifest, secondaryManifest),
   );
-  const merged = mergePlatformUpdateManifests(platform, primaryManifest, secondaryManifest);
 
-  yield* fs.writeFileString(outputPath, serializePlatformUpdateManifest(platform, merged));
+  const serialized = yield* attemptUpdateManifest(() =>
+    serializePlatformUpdateManifest(platform, merged),
+  );
+  yield* fs.writeFileString(outputPath, serialized);
 });
 
 export const mergeUpdateManifestsCommand = Command.make(