Truthful 401 notice: distinguish a server-rejected valid credential from a missing login

src/Capacitor.Cli.Core/Auth/AuthRejectionNotice.cs

@@ -0,0 +1,99 @@
+namespace Capacitor.Cli.Core.Auth;
+
+/// <summary>How the stored credential relates to a 401 the server just returned.</summary>
+public enum StoredCredentialState {
+    /// <summary>No usable stored token — the caller genuinely is not logged in.</summary>
+    Missing,
+
+    /// <summary>A token is stored but was minted by a different server than the target.</summary>
+    WrongServer,
+
+    /// <summary>A token is stored but expired (and the recovery's refresh evidently failed).</summary>
+    Expired,
+
+    /// <summary>The stored token is unexpired and bound to the target — the server rejected a
+    /// credential that looks perfectly valid locally.</summary>
+    LooksValid,
+}
+
+/// <summary>
+/// Builds the user-facing line for a request the server answered 401 AFTER the one-shot
+/// re-read-and-refresh recovery (<c>TokenStore.RecoverForServerAsync</c>) already ran.
+///
+/// <para>The MCP servers used to answer every such 401 with a flat
+/// "Not logged in. Run 'kcap login' on the host shell." — factually wrong in the incident
+/// that motivated this: a server-side signing-key rotation 401'd a token that
+/// <c>kcap status</c> concurrently (and correctly) reported as valid, so the user read the
+/// two surfaces as contradicting each other, concluded <c>kcap login</c> was ineffective,
+/// and reached for a daemon restart — which never helps, because every process re-reads the
+/// same token store. The message now says what is actually true for each store state; the
+/// legacy wording survives byte-identical for the genuinely-logged-out case.</para>
+/// </summary>
+public static class AuthRejectionNotice {
+    public const string NotLoggedIn = "Not logged in. Run 'kcap login' on the host shell.";
+
+    /// <summary>Pure classification of a raw store snapshot against the request's target server.</summary>
+    public static StoredCredentialState Classify(StoredTokens? stored, string targetBaseUrl) {
+        if (stored is null) return StoredCredentialState.Missing;
+
+        // An unbound (pre-upgrade) token is treated as bound — same rule as TokenStore's
+        // BoundToTarget: there is nothing to contradict.
+        if (stored.ServerUrl is not null && !ServerIdentity.SameServer(stored.ServerUrl, targetBaseUrl)) {
+            return StoredCredentialState.WrongServer;
+        }
+
+        return stored.IsExpired ? StoredCredentialState.Expired : StoredCredentialState.LooksValid;
+    }
+
+    public static string Render(StoredCredentialState state, StoredTokens? stored, string targetBaseUrl) =>
+        state switch {
+            StoredCredentialState.Missing => NotLoggedIn,
+
+            StoredCredentialState.Expired =>
+                "Your kcap login has expired and an automatic refresh did not succeed. " +
+                "Run 'kcap login' on the host shell.",
+
+            StoredCredentialState.WrongServer =>
+                $"Stored login was issued by {stored?.ServerUrl} but this request targets {targetBaseUrl}. " +
+                $"Run 'kcap login' (or switch profiles with 'kcap use') to authenticate against {targetBaseUrl}.",
+
+            // The stored token is unexpired and bound to this server, was re-read from disk and
+            // re-sent, and the server still said 401. Locally there is nothing left to fix —
+            // this is the server's auth state having moved (a restart that rotated the signing
+            // key, or an auth incident). Say so, and steer AWAY from the daemon-restart
+            // superstition the incident produced.
+            _ =>
+                $"The server rejected kcap's credentials (HTTP 401) even after re-reading the token store — " +
+                $"yet the stored login for {stored?.GitHubUsername} looks valid locally ({DescribeExpiry(stored)}). " +
+                "This usually means the server's auth state changed (a restart or auth incident). " +
+                "Run 'kcap login' on the host shell to mint a fresh credential — restarting the daemon will not help. " +
+                "If a fresh login still hits this, the server is mid-incident; retry later.",
+        };
+
+    /// <summary>
+    /// Store-inspecting convenience for the MCP servers' 401 sites. Raw, non-mutating read —
+    /// deliberately never the refresh-aware accessor, which could rotate a credential just to
+    /// build an error string. Any store fault degrades to the legacy message rather than
+    /// replacing an auth diagnosis with an IO stack trace.
+    /// </summary>
+    public static async Task<string> ForPersistentUnauthorizedAsync(string targetBaseUrl, CancellationToken ct = default) {
+        try {
+            var profile = await TokenStore.ResolveProfileNameAsync(ct);
+            var stored  = await TokenStore.LoadForProfileAsync(profile, ct);
+
+            return Render(Classify(stored, targetBaseUrl), stored, targetBaseUrl);
+        } catch {
+            return NotLoggedIn;
+        }
+    }
+
+    static string DescribeExpiry(StoredTokens? stored) {
+        if (stored is null) return "expiry unknown";
+
+        var remaining = stored.ExpiresAt - DateTimeOffset.UtcNow;
+
+        return remaining.TotalHours >= 1
+            ? $"expires in {remaining.TotalHours:F0}h"
+            : $"expires in {Math.Max(1, remaining.TotalMinutes):F0}m";
+    }
+}

src/Capacitor.Cli/Commands/McpAnalyticsServer.cs

@@ -17,7 +17,7 @@ namespace Capacitor.Cli.Commands;
 /// rejection reasons. Structure cloned from McpMemoryServer.
 /// </summary>
 static class McpAnalyticsServer {
-    internal const string NotLoggedInMessage = "Not logged in. Run 'kcap login' on the host shell.";
+    internal const string NotLoggedInMessage = AuthRejectionNotice.NotLoggedIn;
 
     internal const string NotSupportedMessage =
         "This server does not support analytics queries — upgrade kcap-server.";
@@ -182,6 +182,14 @@ internal static async Task<string> HandleToolCallAsync(
 
             var body = await httpResponse.Content.ReadAsStringAsync();
 
+            // The 401 wording is store-aware (a locally-valid stored credential the
+            // server rejects must not read as "not logged in"), which needs an async store
+            // read — resolved here so MapResponse stays a pure, unit-testable mapper (its own
+            // 401 arm remains as the fallback wording).
+            if (httpResponse.StatusCode == HttpStatusCode.Unauthorized) {
+                return BuildToolResult(id, await AuthRejectionNotice.ForPersistentUnauthorizedAsync(baseUrl), isError: true);
+            }
+
             return BuildToolResult(id, MapResponse(toolName, httpResponse.StatusCode, body, out var isError), isError);
         } catch (ArgumentException ex) {
             return BuildToolResult(id, $"Error: {ex.Message}", isError: true);

src/Capacitor.Cli/Commands/McpFlowResultServer.cs

@@ -246,7 +246,7 @@ async Task<string> TimedDispatchToolCallAsync(JsonNode callId, JsonObject callRe
                 return ("Result recorded. You may end your reply now.", false);
 
             if (response.StatusCode == HttpStatusCode.Unauthorized)
-                return ("Not logged in. Run 'kcap login' on the host shell.", true);
+                return (await AuthRejectionNotice.ForPersistentUnauthorizedAsync(apiRoot), true);
 
             var errorNode = TryParse(responseBody);
             var code      = errorNode?["error"]?.GetValue<string>();
@@ -322,7 +322,7 @@ async Task<string> TimedDispatchToolCallAsync(JsonNode callId, JsonObject callRe
                 return ("Message sent to the flow driver. It will be delivered with the driver's next flow call — you may continue.", false);
 
             if (response.StatusCode == HttpStatusCode.Unauthorized)
-                return ("Not logged in. Run 'kcap login' on the host shell.", true);
+                return (await AuthRejectionNotice.ForPersistentUnauthorizedAsync(apiRoot), true);
 
             var responseBody = await response.Content.ReadAsStringAsync();
             var errorNode    = TryParse(responseBody);

src/Capacitor.Cli/Commands/McpFlowsServer.cs

@@ -242,7 +242,7 @@ internal static async Task<string> HandleToolCallAsync(
                 var postBody = await postResponse.Content.ReadAsStringAsync();
 
                 if (postResponse.StatusCode == HttpStatusCode.Unauthorized)
-                    return BuildToolResult(id, "Not logged in. Run 'kcap login' on the host shell.", isError: true);
+                    return BuildToolResult(id, await AuthRejectionNotice.ForPersistentUnauthorizedAsync(apiRoot), isError: true);
 
                 // Catalog-start protocol-v2 skew seam (404 means an old server, before any run
                 // started) plus an explicit-vendor echo check once the route matched.
@@ -334,7 +334,7 @@ internal static async Task<string> HandleToolCallAsync(
                     // send already had its go) is an auth problem, not a vendor one — say so, rather
                     // than printing a raw HTTP 401 the caller would read as a flow rejection.
                     if (retryResponse.StatusCode == HttpStatusCode.Unauthorized)
-                        return BuildToolResult(id, "Not logged in. Run 'kcap login' on the host shell.", isError: true);
+                        return BuildToolResult(id, await AuthRejectionNotice.ForPersistentUnauthorizedAsync(apiRoot), isError: true);
 
                     if (CheckVendorOverrideResult(toolName, preference, retryResponse.StatusCode, retryResponse.IsSuccessStatusCode, retryBody, out var retryRunIdToClose) is { } retryVendorCheck) {
                         if (retryRunIdToClose is not null)
@@ -389,7 +389,7 @@ internal static async Task<string> HandleToolCallAsync(
             var body = await httpResponse.Content.ReadAsStringAsync();
 
             if (httpResponse.StatusCode == HttpStatusCode.Unauthorized) {
-                return BuildToolResult(id, "Not logged in. Run 'kcap login' on the host shell.", isError: true);
+                return BuildToolResult(id, await AuthRejectionNotice.ForPersistentUnauthorizedAsync(apiRoot), isError: true);
             }
 
             if (!httpResponse.IsSuccessStatusCode) {
@@ -432,7 +432,8 @@ internal static async Task<string> HandleToolCallAsync(
     /// the refresh flow for WorkOS / GitHubApp), update the client's <c>Authorization</c>
     /// header, and retry the same request once. If refresh fails (genuinely not logged in
     /// or refresh-token expired), the original 401 is returned and the caller surfaces the
-    /// friendly "Not logged in" message.
+    /// store-aware <see cref="AuthRejectionNotice"/> line (which keeps the legacy
+    /// "Not logged in" wording only for a genuinely missing login).
     /// </summary>
     static async Task<HttpResponseMessage> SendWithRefreshRetryAsync(
             HttpClient client, string baseUrl, Func<HttpClient, CancellationToken, Task<HttpResponseMessage>> send,
@@ -1392,7 +1393,7 @@ static async Task<PollResult> PollUntilTerminalAsync(HttpClient client, string a
                 }
 
                 if (resp.StatusCode == HttpStatusCode.Unauthorized)
-                    return new("Not logged in. Run 'kcap login' on the host shell.", true);
+                    return new(await AuthRejectionNotice.ForPersistentUnauthorizedAsync(apiRoot), true);
 
                 // Fix #4: non-transient 4xx (e.g. 400, 403, 409 budget_unverifiable) fail
                 // immediately — coded bodies surface via FormatFlowStartError like the POST path.
@@ -1502,7 +1503,7 @@ static async Task<PollResult> PollStatusUntilTerminalAsync(
 
             using (resp) {
                 if (resp.StatusCode == HttpStatusCode.Unauthorized)
-                    return new("Not logged in. Run 'kcap login' on the host shell.", true);
+                    return new(await AuthRejectionNotice.ForPersistentUnauthorizedAsync(apiRoot), true);
 
                 var statusCode = (int)resp.StatusCode;
                 if (statusCode is >= 400 and < 500) {

src/Capacitor.Cli/Commands/McpMemoryServer.cs

@@ -12,7 +12,7 @@
 namespace Capacitor.Cli.Commands;
 
 static class McpMemoryServer {
-    internal const string NotLoggedInMessage = "Not logged in. Run 'kcap login' on the host shell.";
+    internal const string NotLoggedInMessage = AuthRejectionNotice.NotLoggedIn;
 
     public static async Task<int> RunAsync(string baseUrl) {
         var cwdRepoHash = await ResolveCwdRepoHashAsync();
@@ -187,7 +187,7 @@ internal static async Task<string> HandleToolCallAsync(
             var body = await httpResponse.Content.ReadAsStringAsync();
 
             if (httpResponse.StatusCode == HttpStatusCode.Unauthorized) {
-                return BuildToolResult(id, NotLoggedInMessage, isError: true);
+                return BuildToolResult(id, await AuthRejectionNotice.ForPersistentUnauthorizedAsync(baseUrl), isError: true);
             }
 
             if (!httpResponse.IsSuccessStatusCode) {
@@ -210,7 +210,8 @@ internal static async Task<string> HandleToolCallAsync(
     /// the refresh flow for WorkOS / GitHubApp), update the client's <c>Authorization</c>
     /// header, and retry the same request once. If refresh fails (genuinely not logged in
     /// or refresh-token expired), the original 401 is returned and the caller surfaces the
-    /// friendly "Not logged in" message.
+    /// store-aware <see cref="AuthRejectionNotice"/> line (which keeps the legacy
+    /// "Not logged in" wording only for a genuinely missing login).
     /// </summary>
     static async Task<HttpResponseMessage> SendWithRefreshRetryAsync(HttpClient client, string baseUrl, Func<HttpClient, Task<HttpResponseMessage>> send) {
         var response = await send(client);

src/Capacitor.Cli/Commands/McpSessionsServer.cs

@@ -12,7 +12,7 @@
 namespace Capacitor.Cli.Commands;
 
 static class McpSessionsServer {
-    internal const string NotLoggedInMessage = "Not logged in. Run 'kcap login' on the host shell.";
+    internal const string NotLoggedInMessage = AuthRejectionNotice.NotLoggedIn;
 
     public static async Task<int> RunAsync(string baseUrl) {
         var cwdRepoHash = await ResolveCwdRepoHashAsync();
@@ -183,7 +183,7 @@ internal static async Task<string> HandleToolCallAsync(
             var body = await httpResponse.Content.ReadAsStringAsync();
 
             if (httpResponse.StatusCode == HttpStatusCode.Unauthorized) {
-                return BuildToolResult(id, NotLoggedInMessage, isError: true);
+                return BuildToolResult(id, await AuthRejectionNotice.ForPersistentUnauthorizedAsync(baseUrl), isError: true);
             }
 
             if (!httpResponse.IsSuccessStatusCode) {
@@ -219,7 +219,7 @@ static async Task<string> HandleSearchSessionsAsync(
             var       body  = await first.Content.ReadAsStringAsync();
 
             if (first.StatusCode == HttpStatusCode.Unauthorized) {
-                return BuildToolResult(id, NotLoggedInMessage, isError: true);
+                return BuildToolResult(id, await AuthRejectionNotice.ForPersistentUnauthorizedAsync(baseUrl), isError: true);
             }
 
             if (!first.IsSuccessStatusCode) {
@@ -269,7 +269,8 @@ static async Task<string> HandleSearchSessionsAsync(
     /// the refresh flow for WorkOS / GitHubApp), update the client's <c>Authorization</c>
     /// header, and retry the same request once. If refresh fails (genuinely not logged in
     /// or refresh-token expired), the original 401 is returned and the caller surfaces the
-    /// friendly "Not logged in" message.
+    /// store-aware <see cref="AuthRejectionNotice"/> line (which keeps the legacy
+    /// "Not logged in" wording only for a genuinely missing login).
     /// </summary>
     static async Task<HttpResponseMessage> SendWithRefreshRetryAsync(HttpClient client, string baseUrl, Func<HttpClient, Task<HttpResponseMessage>> send) {
         var response = await send(client);

src/Capacitor.Cli/Commands/McpWorkItemsServer.cs

@@ -17,7 +17,7 @@ namespace Capacitor.Cli.Commands;
 /// memory this server has no repo/machine context to resolve — the only per-call input is the
 /// session id and the declare selector, both carried in the tool arguments.</summary>
 static class McpWorkItemsServer {
-    internal const string NotLoggedInMessage = "Not logged in. Run 'kcap login' on the host shell.";
+    internal const string NotLoggedInMessage = AuthRejectionNotice.NotLoggedIn;
 
     internal const string NoSessionIdMessage =
         "No session id: pass session_id explicitly or run inside a kcap-hooked session (KCAP_SESSION_ID or CODEX_THREAD_ID).";
@@ -176,7 +176,7 @@ string     baseUrl
             var body = await httpResponse.Content.ReadAsStringAsync();
 
             if (httpResponse.StatusCode == HttpStatusCode.Unauthorized) {
-                return BuildToolResult(id, NotLoggedInMessage, isError: true);
+                return BuildToolResult(id, await AuthRejectionNotice.ForPersistentUnauthorizedAsync(baseUrl), isError: true);
             }
 
             if (!httpResponse.IsSuccessStatusCode) {
@@ -199,7 +199,8 @@ string     baseUrl
     /// the refresh flow for WorkOS / GitHubApp), update the client's <c>Authorization</c>
     /// header, and retry the same request once. If refresh fails (genuinely not logged in
     /// or refresh-token expired), the original 401 is returned and the caller surfaces the
-    /// friendly "Not logged in" message.
+    /// store-aware <see cref="AuthRejectionNotice"/> line (which keeps the legacy
+    /// "Not logged in" wording only for a genuinely missing login).
     /// </summary>
     static async Task<HttpResponseMessage> SendWithRefreshRetryAsync(HttpClient client, string baseUrl, Func<HttpClient, Task<HttpResponseMessage>> send) {
         var response = await send(client);