@@ -138,6 +138,27 @@ EMBEDDING_FAIL_OPEN=false
 # listed here on purpose: they still appear in application.properties, but no Java
 # code reads any azure.openai.* property any more, so setting them changes nothing.
 
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# OPTIONAL — DeepSQL Agent runtime (chat TUI + the web Agent tab)
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# The agent surfaces — `deepsql agent` and the Agent tab — are served by a separate
+# runtime, not by the backend. The defaults below are Compose service names, so on a
+# native (non-Compose) run they resolve to nothing and every agent turn fails with
+# "cannot reach the agent runtime at http://deepsql-agent:8787". Point them at wherever
+# the runtime actually listens. Everything else in DeepSQL works without them.
+#
+# AGENT_WEBUI_URL         where the agent runtime serves its API (default http://deepsql-agent:8787)
+# AGENT_PROVISIONER_URL   per-user profile provisioning endpoint (default http://deepsql-agent:8788/provision)
+# AGENT_PROVISION_SECRET  shared secret for the above. Unset, the backend logs
+#                         "agent.provision-secret is unset — skipping" and never creates
+#                         the u-<user> profile, so the agent has no identity to run as.
+#
+# Native runs: start the provisioner with `python3 scripts/local-agent-provisioner.py`.
+# See AGENTS.md for the full sequence, and agent/README.md for the runtime itself.
+#AGENT_WEBUI_URL=http://127.0.0.1:8787
+#AGENT_PROVISIONER_URL=http://127.0.0.1:8788/provision
+#AGENT_PROVISION_SECRET=
+
 # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 # VECTOR STORE — choose one mode
 # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
@@ -6,7 +6,17 @@
 name: deepsql-agent
 version: 0.1.0
 description: "DeepSQL DBA agent — grounded, read-only database assistant over the DeepSQL MCP tools (BI queries, schema exploration, index advice, slow-query optimization, workload analysis)."
-hermes_requires: ">=0.12.0"
+# The upper bound is evidence, not caution: verified on 2026-08-06 against upstream
+# v0.20.0 (2026.8.3), where every agent API call answers
+# 401 {"detail":"Unauthorized","reason":"no_cookie"}. That release requires a login
+# cookie on /api/session/new and friends, and AgentChatClient authenticates in no way
+# at all — the Compose deployment relies on a reverse proxy injecting
+# X-DeepSQL-User / X-DeepSQL-Token, which does not exist on a native run.
+#
+# The floor stays at 0.12.0 because nothing below it has been tested; it is not a
+# claim that 0.12.0 works. Raise the ceiling only once the backend authenticates to
+# the runtime and a real turn has been seen to complete.
+hermes_requires: ">=0.12.0,<0.20.0"
 author: "DeepSQL"
 license: "proprietary"
 
 
@@ -54,9 +54,21 @@ public record AgentReply(boolean ok, String text, List<String> toolSteps, String
      * when present, otherwise create a fresh session and auto-approve its read-only
      * tool surface (channels are non-interactive). Returns null on failure.
      */
+    /**
+     * Why a session could not be created, for callers that surface a reason to the user.
+     * {@code sessionId} non-null means success and {@code failureReason} is null.
+     */
+    public record SessionAttempt(String sessionId, String failureReason) {
+        boolean ok() { return sessionId != null; }
+    }
+
     public String ensureSession(String profile, String existingSessionId) {
+        return ensureSessionDetailed(profile, existingSessionId).sessionId();
+    }
+
+    public SessionAttempt ensureSessionDetailed(String profile, String existingSessionId) {
         if (existingSessionId != null && !existingSessionId.isBlank()) {
-            return existingSessionId;
+            return new SessionAttempt(existingSessionId, null);
         }
         try {
             JsonNode created = postJson("/api/session/new", Map.of(
@@ -66,18 +78,26 @@ public String ensureSession(String profile, String existingSessionId) {
             if (sessionId == null) sessionId = text(created.path("session_id"));
             if (sessionId == null) {
                 log.warn("Agent session/new returned no session_id for profile {}", profile);
-                return null;
+                return new SessionAttempt(null,
+                    "the agent runtime accepted the request but returned no session id");
             }
             // Best-effort: auto-approve read-only tools so the turn doesn't block on approval.
             try {
                 postJson("/api/session/yolo", Map.of("session_id", sessionId, "enabled", true));
             } catch (Exception e) {
                 log.debug("session/yolo failed for {}: {}", sessionId, e.getMessage());
             }
-            return sessionId;
+            return new SessionAttempt(sessionId, null);
         } catch (Exception e) {
-            log.warn("Could not create agent session for profile {}: {}", profile, e.getMessage());
-            return null;
+            // toString(), not getMessage(): a NullPointerException or a connect failure
+            // carries a null message, and "Could not create agent session: null" says
+            // nothing at all. The class name alone distinguishes "refused to connect"
+            // from "rejected the request". The exception is attached so the stack is
+            // available at DEBUG without making the common case unreadable.
+            log.warn("Could not create agent session for profile {} at {}: {}",
+                profile, webuiUrl, e.toString());
+            log.debug("agent session/new failure detail", e);
+            return new SessionAttempt(null, describe(e));
         }
     }
 
@@ -163,11 +183,41 @@ private JsonNode postJson(String path, Map<String, Object> body) throws Exceptio
             .build();
         HttpResponse<String> resp = http.send(req, HttpResponse.BodyHandlers.ofString());
         if (resp.statusCode() / 100 != 2) {
-            throw new RuntimeException("POST " + path + " -> HTTP " + resp.statusCode());
+            // The body carries the reason the status code alone does not. An agent
+            // runtime hardened to require a login answers
+            // {"detail":"Unauthorized","reason":"no_cookie"} — without that, a 401 is
+            // indistinguishable from the agent being down, which sends whoever is
+            // debugging after the wrong fix. Truncated so an HTML error page cannot
+            // land whole in the log.
+            String detail = resp.body() == null ? "" : resp.body().strip();
+            if (detail.length() > 300) detail = detail.substring(0, 300) + "…";
+            throw new RuntimeException("POST " + path + " -> HTTP " + resp.statusCode()
+                + (detail.isEmpty() ? "" : " " + detail));
         }
         return objectMapper.readTree(resp.body());
     }
 
+    /**
+     * A one-line reason fit to show an operator. The two failures look identical from
+     * the outside and have opposite fixes: nothing is listening (start the runtime, or
+     * agent.webui-url points at the wrong place) versus something answered and said no
+     * (authenticate to it, or its API changed).
+     */
+    private String describe(Exception e) {
+        if (e instanceof java.net.ConnectException || e instanceof java.net.UnknownHostException) {
+            return "cannot reach the agent runtime at " + webuiUrl
+                + " — is it running, and is agent.webui-url correct?";
+        }
+        if (e instanceof java.net.http.HttpTimeoutException) {
+            return "the agent runtime at " + webuiUrl + " did not respond in time";
+        }
+        String msg = e.getMessage();
+        if (msg == null || msg.isBlank()) {
+            return "the agent runtime at " + webuiUrl + " failed with " + e.getClass().getSimpleName();
+        }
+        return "the agent runtime at " + webuiUrl + " rejected the request: " + msg;
+    }
+
     private String text(JsonNode node) {
         return (node == null || node.isMissingNode() || node.isNull()) ? null : node.asText(null);
     }
 
@@ -53,11 +53,17 @@ public TurnResult runTurn(String connectionId, String conversationId, String mes
         }
 
         String existingSession = conv == null ? null : conv.getAgentSessionId();
-        String sessionId = agentChatClient.ensureSession(profile, existingSession);
-        if (sessionId == null) {
+        // Detailed variant: "unavailable right now" reads as a transient outage and sends
+        // people away to wait, when the real causes — the runtime is not running, the URL
+        // is wrong, or it demands a login the backend never performs — stay broken until
+        // somebody acts. Report what actually happened.
+        AgentChatClient.SessionAttempt attempt =
+            agentChatClient.ensureSessionDetailed(profile, existingSession);
+        if (attempt.sessionId() == null) {
             return new TurnResult(false, null, List.of(), conv == null ? null : conv.getId(),
-                "the DeepSQL agent is unavailable right now");
+                "DeepSQL agent unavailable: " + attempt.failureReason());
         }
+        String sessionId = attempt.sessionId();
 
         if (conv == null) {
             conv = conversationService.create(connectionId, sessionId, deriveTitle(message));