Known issues: document more Positron and RStudio bugs with workarounds

Author: HenrikBengtsson

DESCRIPTION

@@ -1,5 +1,5 @@
 Package: progressr
-Version: 0.17.0-9000
+Version: 0.17.0-9001
 Title: An Inclusive, Unifying API for Progress Updates
 Description: A minimal, unifying API for scripts and packages to report progress updates from anywhere including when using parallel processing.  The package is designed such that the developer can to focus on what progress should be reported on without having to worry about how to present it.  The end user has full control of how, where, and when to render these progress updates, e.g. in the terminal using utils::txtProgressBar(), cli::cli_progress_bar(), in a graphical user interface using utils::winProgressBar(), tcltk::tkProgressBar() or shiny::withProgress(), via the speakers using beepr::beep(), or on a file system via the size of a file. Anyone can add additional, customized, progression handlers. The 'progressr' package uses R's condition framework for signaling progress updated. Because of this, progress can be reported from almost anywhere in R, e.g. from classical for and while loops, from map-reduce API:s like the lapply() family of functions, 'purrr', 'plyr', and 'foreach'. It will also work with parallel processing via the 'future' framework, e.g. future.apply::future_lapply(), furrr::future_map(), and 'foreach' with 'doFuture'. The package is compatible with Shiny applications.
 Authors@R: c(person("Henrik", "Bengtsson",

vignettes/progressr-91-appendix.md

@@ -157,9 +157,44 @@ risk it would never finish and block all of the following progressors.
 
 ## Known Issues
 
-### Positron
+### RStudio bug #16331: Setting global progressr handlers during startup does not work
 
-#### Setting global progressr handlers during startup does not work
+Setting the global progressr handler in `~/.Rprofile` does _not_ work
+in RStudio 2025.09:
+
+```r
+if (requireNamespace("progressr", quietly = TRUE)) {
+  progressr::handlers(global = TRUE)
+}
+```
+
+This is due to a [bug introduced in RStudio
+2025.09](https://github.com/rstudio/rstudio/issues/16331), which has
+been fixed for the next release RStudio 2025.11. If you are using
+RStudio 2025.09, the workaround is to instead use:
+
+```r
+if (requireNamespace("progressr", quietly = TRUE)) {
+  progressr::handlers(global = TRUE)
+
+  ## Workaround for RStudio 2025.09 console bug #16331
+  if (nzchar(Sys.getenv("RSTUDIO")) && !nzchar(Sys.getenv("RSTUDIO_TERM"))) {
+    invisible(addTaskCallback(function(...) {
+      ver <- RStudio.Version()$version
+      if (ver >= "2025.09" && ver < "2025.11") {
+        message("Workaround for RStudio 2025.09 bug #16331: Added progressr global handler")
+        progressr::handlers(global = TRUE)
+      } else {
+        warning("Workaround for RStudio 2025.09 bug #16331: Not needed in RStudio v", ver, ". Please remove task callback 'rstudio::progressr::once' in your Rprofile startup file", call. = FALSE, immediate. = TRUE)
+      }
+      removeTaskCallback("rstudio::progressr::once")
+    }, name = "rstudio::progressr::once"))
+  }
+}
+```
+
+
+### Positron bug #6892: Setting global progressr handlers during startup does not work
 
 Positron does not support setting global calling handlers during R's
 startup process, e.g. in `~/.Rprofile`. Even if such handlers are
@@ -176,23 +211,44 @@ if (requireNamespace("progressr", quietly = TRUE)) {
 ```
 
 will have no effect. If used, the workaround is to manually
-re-registering all calling handlers _at the R prompt_, which can be
-done as:
+re-registering all calling handlers, which can be done as:
 
 ```r
-globalCallingHandlers(globalCallingHandlers(NULL))
+if (requireNamespace("progressr", quietly = TRUE)) {
+  progressr::handlers(global = TRUE)
+
+  ## Workaround for Positron (>= 2025.09) bug #16331
+  if (nzchar(Sys.getenv("POSITRON"))) local({
+    ver <- numeric_version(Sys.getenv("POSITRON_VERSION"))
+    if (ver >= "2025.09") {
+      message("Workaround for Positron (>= 2025.09) bug #6892: progressr global handler will be installed *after* the next call has been completed")
+      invisible(addTaskCallback(function(...) {
+        message("Workaround for Positron (>= 2025.09) bug #6892: re-installed progressr global handler")
+        globalCallingHandlers(globalCallingHandlers(NULL))
+        removeTaskCallback("positron::progressr::once")
+      }, name = "positron::progressr::once"))
+    }
+  })
+}
 ```
 
 Alternatively, call:
 
+```r
+globalCallingHandlers(globalCallingHandlers(NULL))
+```
+
+or
+
 ```r
 progressr::handlers(global = FALSE)  ## important
 progressr::handlers(global = TRUE)
 ```
 
+at the prompt.
 
 
-#### Messages add a extra newline before the final progress step
+### Positron: Messages add extra newline before the final progress step
 
 One of the features of **progressr** is that messages are buffered
 during progress reporting and relayed as soon as possible, which
@@ -223,9 +279,7 @@ Positron, e.g. [Bug #9486](https://github.com/posit-dev/positron/issues/9486)
 (2025-09-18).
 
 
-### Jupyter Notebook and Jupyter Lab
-
-#### Reporting progress to stderr does not work
+### Jupyter: Reporting progress to stderr (default) does not work
 
 The default for most terminal progress renders, including the ones for
 **progressr**, display the progress on standard error (stderr). Due to
@@ -277,7 +331,7 @@ y <- slow_sum(1:20)
 ```
 
 
-#### handlers("progress") output is messy
+### Jupyter bug #732 - handlers("progress") output is messy
 
 Jupyter has other outputting issues. Specifically, Jupyter [injects an
 _extra_ newline at the end of every
@@ -341,7 +395,7 @@ depends on it.  The roadmap for developing the API is roughly:
       i.e. `handlers(global = TRUE)` and `handlers(global = FALSE)`
 
 * [ ] Make it possible to create a progressor also in the global
-      environment (see 'Known issues' above)
+      environment (see 'Known Issues' above)
 
 * [ ] Add support for nested progress updates