beatrina 0.8.6 → 0.8.7

package/failsafe/serve.R

@@ -56,6 +56,11 @@ source(file.path(here, "settings.R"))
 source(file.path(here, "fileio.R"))
 source(file.path(here, "journal.R"))
 source(file.path(here, "ai-store.R"))
+# "Restart, keep variables": the supervisor never reads a kept workspace; it
+# only checks the token (keep_token_ok) and carries it to the next worker.
+source(file.path(here, "workspace-keep.R"))
+# Which documents this session has open — the session's record, not the page's.
+source(file.path(here, "session-documents.R"))
 
 # Apply an administrator-owned desktop policy before any subsystem reads its
 # environment. Invalid or user-writable policy fails closed at the shared
@@ -319,6 +324,17 @@ sockets$open <- list()
 # connects. Without replaying it, every page that opens later sits on
 # "connecting…" forever waiting for a frame that was broadcast to nobody.
 sockets$hello <- NULL
+# A kept workspace for the NEXT ready worker: set by `restart {resume}` or, in a
+# handoff successor, by CARMAR_RESUME_TOKEN. Consumed once, on `ready`.
+sockets$resume_pending <- if (keep_token_ok(Sys.getenv("CARMAR_RESUME_TOKEN")))
+  Sys.getenv("CARMAR_RESUME_TOKEN") else NULL
+# The restore's report, kept for 120 s so a page that follows a handoff — and
+# connects after the restore finished — still hears what came back.
+sockets$resume_report <- NULL
+# The documents open in this session (spike/session-documents.R), as the pages
+# last reported them. A handoff successor starts with its predecessor's list.
+sockets$session_documents <- session_documents_decode(Sys.getenv("CARMAR_SESSION_DOCUMENTS"))
+Sys.unsetenv("CARMAR_SESSION_DOCUMENTS")
 sockets$worker_recovering <- FALSE
 sockets$worker_restart_attempts <- 0L
 sockets$worker_restart_after <- 0
@@ -1078,6 +1094,8 @@ start_sibling_session <- function() {
 # Ops a declared MCP agent is refused outright: raw evaluation (it must go
 # through a visible chunk_run) and the user's credentials.
 AGENT_REFUSED <- c("exec", "interrupt", "force_stop", "restart", "session_upgrade", "session_restart", "debug_cmd", "ai-key",
+                   # A copy of every object in the session, written to disk.
+                   "suspend", "suspend_cancel",
                    # The user's AI conversations. An agent reading them would be
                    # reading every question the user has asked about their data,
                    # including the ones they asked about a different agent.
@@ -1383,6 +1401,11 @@ FORWARDED <- c("env", "obj", "struct", "view", "colstats", "rm", "packages", "do
                "package_action", "package_help", "project_status", "project_action", "help", "wd",
                "parse", "complete", "files", "import", "readfile", "writefile", "writefiles_atomic",
                "hover", "format", "sniff",
+               # "Restart, keep variables", step one (spike/workspace-keep.R).
+               # Page-only in both senses: AGENT_REFUSED above, the class gate
+               # in handle_frame. Step two, `resume`, is deliberately NOT here —
+               # only the supervisor asks it, after a restart it performed.
+               "suspend",
                # The file tree's New Folder, Rename and Delete. These MUTATE
                # the filesystem, which is a wider door than the read-only ops
                # around them, so the bar they clear is stated rather than
@@ -1865,6 +1888,10 @@ app <- list(
     audit("socket-open", sockets = length(sockets$open), class = rec$class,
           user = rec$user)
     if (!is.null(sockets$hello)) try(ws$send(sockets$hello), silent = TRUE)
+    if (!is.null(sockets$resume_report) && isTRUE(rec$class %in% PAGE_ONLY_CLASSES)
+        && as.numeric(difftime(Sys.time(), sockets$resume_report$at, units = "secs")) < 120) {
+      try(ws$send(sockets$resume_report$payload), silent = TRUE)
+    }
     # …and the give-up, when there is one. A page that arrives after the
     # respawn ceiling has no ready frame coming and would otherwise sit on
     # "connecting…" forever with nothing on screen saying why.
@@ -3166,9 +3193,11 @@ handoff_page_url <- function(installed, cap) {
 #' only ever mean "spawned, exiting".
 #' @param mode "upgrade" or "restart".
 #' @param force Kill a busy worker rather than refuse (restart only).
+#' @param resume A kept-workspace token (spike/workspace-keep.R) the successor's
+#'   first worker restores, or NULL for a fresh R.
 #' @return The reply the caller sends: ok/from/to/page/started/mode/force,
 #'   or ok = FALSE with error and reason.
-session_handoff_begin <- function(mode = "upgrade", force = FALSE) {
+session_handoff_begin <- function(mode = "upgrade", force = FALSE, resume = NULL) {
   mode <- if (identical(mode, "restart")) "restart" else "upgrade"
   force <- isTRUE(force) && identical(mode, "restart")
   audit_name <- if (identical(mode, "restart")) "session-restart" else "session-upgrade"
@@ -3181,7 +3210,8 @@ session_handoff_begin <- function(mode = "upgrade", force = FALSE) {
   cap <- secure_token(32L)
   page <- handoff_page_url(installed, cap)
   sockets$handoff <- list(to = installed, cap = cap, page = page,
-                          started = Sys.time(), mode = mode, force = force)
+                          started = Sys.time(), mode = mode, force = force,
+                          resume = if (keep_token_ok(resume)) resume else NULL)
   audit(audit_name, from = CARMAR_KERNEL_BUILD, to = installed, force = force)
   # Every page learns where its successor's notebook is — over the gated
   # socket only; the capability never appears in /health. `started` is this
@@ -3189,7 +3219,8 @@ session_handoff_begin <- function(mode = "upgrade", force = FALSE) {
   # which is the only test that also works when the build does not change.
   told <- toJSON(list(type = "session-upgrade", from = CARMAR_KERNEL_BUILD,
                       to = installed, page = page, started = as.numeric(sockets$boot_at),
-                      mode = mode, force = force), auto_unbox = TRUE)
+                      mode = mode, force = force,
+                      keep = !is.null(sockets$handoff$resume)), auto_unbox = TRUE)
   lapply(page_recs(), function(r) try(r$ws$send(told), silent = TRUE))
   session_handoff_spawn()
   list(ok = TRUE, from = CARMAR_KERNEL_BUILD, to = installed, page = page,
@@ -3224,6 +3255,9 @@ session_handoff_spawn <- function() {
   env[["CARMAR_FILE_LAUNCH_CAP"]] <- h$cap
   env[["CARMAR_HANDOFF_FROM"]] <- CARMAR_KERNEL_BUILD
   env[["CARMAR_SESSION_TITLE"]] <- runtime_record$title %||% ""
+  env[["CARMAR_SESSION_DOCUMENTS"]] <- session_documents_encode(sockets$session_documents)
+  # Only a token travels, never a path; the successor re-checks it.
+  env[["CARMAR_RESUME_TOKEN"]] <- h$resume %||% ""
   if (isTRUE(runtime_record$listen)) env[["CARMAR_LISTEN"]] <- "1"
   # The same R this supervisor runs on, and the serve.R beside THIS file —
   # which, after the in-place swap, is the installed build's.
@@ -3480,6 +3514,32 @@ route_internal <- function(cmd, on_reply) {
   list(cmd = cmd, wire_id = wire_id)
 }
 
+#' Ask the fresh worker to restore a kept workspace, and tell every page what
+#' came back. Queued like any command, so a chunk run pressed meanwhile waits
+#' for the restore rather than racing it.
+#' @return Invisibly NULL.
+start_resume <- function() {
+  token <- sockets$resume_pending
+  sockets$resume_pending <- NULL
+  if (!keep_token_ok(token)) return(invisible(NULL))
+  audit("resume-start")
+  routed <- route_internal(list(type = "resume", token = token), on_reply = function(frame) {
+    if (scalar_chr(frame$cwd)) sockets$worker_wd <- frame$cwd
+    report <- list(type = "workspace_restored",
+                   restored = frame$restored %||% 0L,
+                   failed = frame$failed %||% list(), skipped = frame$skipped %||% list(),
+                   wd_missing = frame$wd_missing %||% NULL, error = frame$error %||% NULL)
+    payload <- toJSON(report, auto_unbox = TRUE, null = "null")
+    sockets$resume_report <- list(at = Sys.time(), payload = payload)
+    audit("resume-done", restored = report$restored, failed = length(report$failed),
+          error = !is.null(report$error))
+    pages <- Filter(function(r) isTRUE(r$class %in% PAGE_ONLY_CLASSES), page_recs())
+    lapply(pages, function(r) try(r$ws$send(payload), silent = TRUE))
+  })
+  enqueue_worker_command(routed$cmd, routed$wire_id)
+  invisible(NULL)
+}
+
 #' Tell every page, and REMEMBER it for the pages that are not here yet.
 #'
 #' `sockets$hello` exists because the worker announces itself once, long
@@ -3670,6 +3730,34 @@ handle_frame <- function(message, rec) {
     return(invisible(NULL))
   }
 
+  # The documents this session has open (spike/session-documents.R). Page-only
+  # in BOTH senses: the list is file paths, and a page that could not open a
+  # terminal must not be able to rewrite what the session reopens either.
+  # Replies nothing; the helper's label follows through the runtime record.
+  if (identical(cmd$type, "page-documents")) {
+    if (identical(rec$role, "page") && isTRUE(rec$class %in% PAGE_ONLY_CLASSES)) {
+      sockets$session_documents <- session_documents_clean(cmd$documents)
+      set_runtime_documents(sockets$session_documents)
+    }
+    return(invisible(NULL))
+  }
+
+  # A page asks what this session had open, to reopen it. `others` counts the
+  # OTHER pages attached: a page joining a session another window is showing
+  # must not open the same documents a second time (that window holds their
+  # history leases), so the page reopens only when it is alone.
+  if (identical(cmd$type, "session-documents")) {
+    if (!scalar_chr(cmd$id)) return(invisible(NULL))
+    allowed <- identical(rec$role, "page") && isTRUE(rec$class %in% PAGE_ONLY_CLASSES)
+    others <- Filter(function(r) !identical(r$ws, rec$ws), page_recs())
+    try(rec$ws$send(toJSON(list(
+      type = "session-documents", id = cmd$id,
+      documents = if (allowed) sockets$session_documents else list(),
+      others = length(others),
+      refused = !allowed), auto_unbox = TRUE)), silent = TRUE)
+    return(invisible(NULL))
+  }
+
   # ── the MCP plane ─────────────────────────────────────────────────────────
   # A local agent (Claude Code / Codex via tools/mcp/carmar-mcp.mjs) connects
   # through the same loopback/Origin/Host gates as a page, then DECLARES itself.
@@ -3791,7 +3879,8 @@ handle_frame <- function(message, rec) {
       return(invisible(NULL))
     }
     reply(session_handoff_begin(mode = if (identical(cmd$type, "session_restart")) "restart" else "upgrade",
-                                force = isTRUE(cmd$force)))
+                                force = isTRUE(cmd$force),
+                                resume = if (keep_token_ok(cmd$resume)) cmd$resume else NULL))
     return(invisible(NULL))
   }
   # ── terminals ─────────────────────────────────────────────────────────────
@@ -4163,6 +4252,25 @@ handle_frame <- function(message, rec) {
     return(invisible(NULL))
   }
 
+  # "Restart, keep variables": the save is a copy of the whole session, so it
+  # is page-only in BOTH senses, and its cancel interrupts only a save THIS
+  # page asked for — Interrupt's own gate matches exec routes, never this.
+  if (cmd$type %in% c("suspend", "suspend_cancel") && !isTRUE(rec$class %in% PAGE_ONLY_CLASSES)) {
+    if (scalar_chr(cmd$id)) try(rec$ws$send(toJSON(list(
+      type = cmd$type, id = cmd$id, error = "Only the local notebook page may keep the workspace."
+    ), auto_unbox = TRUE)), silent = TRUE)
+    audit("suspend-refused", reason = "class", class = rec$class %||% "unknown")
+    return(invisible(NULL))
+  }
+  if (identical(cmd$type, "suspend_cancel")) {
+    active <- sockets$worker_active
+    route <- if (!is.null(active)) sockets$worker_routes[[active]] else NULL
+    if (identical(sockets$worker_active_type, "suspend") && !is.null(route) && identical(route$rec, rec)) {
+      audit("suspend-cancel")
+      kernel_interrupt(k)
+    }
+    return(invisible(NULL))
+  }
   if (identical(cmd$type, "project_action") && !isTRUE(rec$class %in% PAGE_ONLY_CLASSES)) {
     if (scalar_chr(cmd$id)) try(rec$ws$send(toJSON(list(
       type = "project_action", id = cmd$id, ok = FALSE, reason = "class",
@@ -4339,11 +4447,12 @@ handle_frame <- function(message, rec) {
   # hello is stale the moment the old worker dies; the new worker's ready frame
   # replaces it via pump() and reaches every open socket.
   if (identical(cmd$type, "restart")) {
-    audit("restart")
+    audit("restart", keep = keep_token_ok(cmd$resume))
     fail_worker_routes("R was restarted — this request was abandoned.")
     try(kernel_stop(k, grace = 1), silent = TRUE)
     k <<- start_execution_worker()
     sockets$hello <- NULL
+    sockets$resume_pending <- if (keep_token_ok(cmd$resume)) cmd$resume else NULL
     sockets$worker_recovering <- FALSE
     sockets$worker_restart_attempts <- 0L
     # An explicit Restart R is the ONE door out of a give-up: the user has
@@ -5167,6 +5276,7 @@ pump <- function() {
     payload <- relay_frame(e)
     if (identical(e$type, "ready")) sockets$hello <- payload
     lapply(sockets$open, function(r) try(r$ws$send(payload), silent = TRUE))
+    if (identical(e$type, "ready") && !is.null(sockets$resume_pending)) start_resume()
     invisible(NULL)
   })
   invisible(NULL)
@@ -5236,6 +5346,8 @@ local({
   Sys.unsetenv("CARMAR_SESSION_TITLE")
   title <- trimws(substr(gsub("[\"\\\\]", "'", gsub("[[:cntrl:]]", " ", title)), 1L, 120L))
   if (nzchar(title)) runtime_record$title <<- title
+  label <- session_documents_label(sockets$session_documents)
+  if (nzchar(label)) runtime_record$documents <<- label
 })
 # CARMAR_LISTEN=1 marks a kernel started headless for published pages (the
 # menu's Listen for Web Pages, the keep-ready daemon). The menu helper shows
@@ -5280,6 +5392,19 @@ set_runtime_title <- function(title) {
   write_runtime()
 }
 
+#' The session's documents, as a label, into the runtime record.
+#'
+#' `documents` is what the menu helper shows in place of the notebook's
+#' generated name ("SezerProfiles.qmd", not "Mellow Yarrow 7Z6"). A flat
+#' string on purpose — helper-sessions.sh reads the record with a bounded sed.
+set_runtime_documents <- function(documents) {
+  label <- session_documents_label(documents)
+  if (identical(runtime_record$documents %||% "", label)) return(invisible(NULL))
+  if (nzchar(label)) runtime_record$documents <<- label
+  else runtime_record$documents <<- NULL
+  write_runtime()
+}
+
 #' A page attached: this kernel is now a session, not a bare listener.
 clear_runtime_listen <- function() {
   if (is.null(runtime_record$listen)) return(invisible(NULL))

package/failsafe/session-documents.R

@@ -0,0 +1,104 @@
+# session-documents.R — which documents a session has open, held by the kernel.
+#
+# Why the kernel, and not the page's storage: every session of one build is
+# served by the SAME notebook file, and the page remembers its open documents
+# per file (lib/open-documents.js). So two sessions share one record, and the
+# later one overwrites the earlier — reopening a session from the menu helper
+# brought back its R (40 objects, 1.9 GB) in front of an empty notebook
+# (owner, 2026-09-14: "it has the objects but not the file").
+#
+# The session is the thing that has an identity here, so the session keeps the
+# list. The page reports it (`page-documents`); a page that attaches to a
+# running session with nobody else on it asks for it back (`session-documents`)
+# and reopens each file. Only paths, names and formats travel — never text:
+# unsaved edits stay in the page that made them, and a document that was never
+# saved is listed by name so the page can SAY it cannot come back.
+#
+# Pure functions; spike/serve.R holds the state. Pinned by
+# spike/test-session-documents.R.
+
+SESSION_DOCUMENTS_MAX <- 64L
+SESSION_DOCUMENT_FORMATS <- c("qmd", "Rmd", "md", "carmd")
+
+#' Validate a page's report into a clean list of documents.
+#'
+#' Anything malformed is dropped row by row, never the whole report: one odd
+#' row must not cost the session the record of the others.
+#'
+#' @param documents What jsonlite made of the frame's `documents` field
+#'   (simplifyVector = TRUE: a data.frame, a list, or NULL).
+#' @return A list of `list(path, name, format, active)`; `path` is "" for a
+#'   document that has no file yet. At most SESSION_DOCUMENTS_MAX rows.
+session_documents_clean <- function(documents) {
+  if (is.null(documents) || !length(documents)) return(list())
+  rows <- if (is.data.frame(documents)) {
+    lapply(seq_len(nrow(documents)), \(i) as.list(documents[i, , drop = FALSE]))
+  } else if (is.list(documents)) {
+    documents
+  } else {
+    return(list())
+  }
+  one <- function(row) {
+    if (!is.list(row)) return(NULL)
+    text_of <- function(value, cap) {
+      if (!is.character(value) || length(value) != 1L || is.na(value)) return(NULL)
+      value <- gsub("[[:cntrl:]]", " ", value)
+      if (nchar(value) > cap) return(NULL)
+      value
+    }
+    path <- text_of(row$path %||% "", 4096L)
+    name <- text_of(row$name %||% "", 200L)
+    format <- text_of(row$format %||% "", 16L)
+    if (is.null(path) || is.null(name) || is.null(format)) return(NULL)
+    # A path is reopened through the file ops, which resolve it themselves;
+    # here it need only be absolute, so a relative string cannot be read
+    # against whatever the worker's cwd is by then.
+    if (nzchar(path) && !grepl("^(/|[A-Za-z]:[/\\\\])", path)) return(NULL)
+    if (!nzchar(path) && !nzchar(trimws(name))) return(NULL)
+    if (!format %in% SESSION_DOCUMENT_FORMATS) format <- "qmd"
+    list(path = path, name = trimws(name), format = format,
+         active = isTRUE(row$active))
+  }
+  cleaned <- Filter(Negate(is.null), lapply(rows, one))
+  # The same file listed twice is one document.
+  paths <- vapply(cleaned, \(row) row$path, character(1))
+  keep <- !nzchar(paths) | !duplicated(paths)
+  head(cleaned[keep], SESSION_DOCUMENTS_MAX)
+}
+
+#' The name a session goes by: its document, not its generated notebook name.
+#'
+#' Flattened for the runtime record, which helper-sessions.sh reads with a
+#' bounded sed — a quote or a backslash would cut every field after it.
+#'
+#' @param documents A list from session_documents_clean().
+#' @return "" when there are none; else the on-screen document's name (the
+#'   first one when none is marked), then " + N more" for the rest.
+session_documents_label <- function(documents) {
+  if (!length(documents)) return("")
+  active <- Filter(\(row) isTRUE(row$active), documents)
+  lead <- if (length(active)) active[[1L]] else documents[[1L]]
+  name <- if (nzchar(lead$path)) basename(lead$path) else lead$name
+  if (!nzchar(lead$path)) name <- sprintf("%s (unsaved)", name)
+  rest <- length(documents) - 1L
+  label <- if (rest > 0L) sprintf("%s + %d more", name, rest) else name
+  trimws(substr(gsub("[\"\\\\]", "'", gsub("[[:cntrl:]]", " ", label)), 1L, 120L))
+}
+
+#' Serialise for a successor supervisor's environment (a session handoff).
+#' @param documents A list from session_documents_clean().
+#' @return A JSON string; "" when there are none.
+session_documents_encode <- function(documents) {
+  if (!length(documents)) return("")
+  as.character(jsonlite::toJSON(documents, auto_unbox = TRUE))
+}
+
+#' Read back what session_documents_encode() wrote; junk yields an empty list.
+#' @param text A JSON string (possibly "").
+#' @return A list from session_documents_clean().
+session_documents_decode <- function(text) {
+  if (!is.character(text) || length(text) != 1L || !nzchar(text)) return(list())
+  parsed <- tryCatch(jsonlite::fromJSON(text, simplifyVector = TRUE),
+                     error = function(e) NULL)
+  session_documents_clean(parsed)
+}

package/host/engine-js.mjs

@@ -93,6 +93,10 @@ export class JsEngine extends StdioEngine {
     return true;
   }
 
+  /** process.kill, replaceable in tests. */
+  get killImpl() { return this._killImpl || process.kill.bind(process); }
+  set killImpl(fn) { this._killImpl = fn; }
+
   /** There is no prompt behind this worker: a console line is refused, not typed. */
   console() { throw new Error("The JavaScript engine has no console prompt."); }
 }

package/host/engine-pool.mjs

@@ -77,6 +77,7 @@ export class EnginePool extends EventEmitter {
       });
       plane.sockets = () => this.sockets();
       plane.on("broadcast", (payload) => this.emit("broadcast", payload));
+      plane.on("broadcast-pages", (payload) => this.emit("broadcast-pages", payload));
       this.planes.set(spec.name, plane);
     }
   }
@@ -329,7 +330,7 @@ export class EnginePool extends EventEmitter {
    * With no engine named it is the primary's — which is what "Restart R" in
    * the page means and what every existing client sends.
    */
-  async restart(engine) {
+  async restart(engine, opts = {}) {
     const key = engineKey(engine, this.primaryName);
     const plane = this.planes.get(key);
     if (!plane) return undefined;
@@ -338,9 +339,14 @@ export class EnginePool extends EventEmitter {
       const r = await this.ensure(key);
       return r.ok ? undefined : undefined;
     }
-    return plane.restart();
+    return plane.restart(key === this.primaryName ? opts : {});
   }
 
+  /** "Restart, keep variables" belongs to the primary (R) engine. */
+  setResumePending(token) { this.primary?.setResumePending(token); }
+  freshResumeReport(now) { return this.primary ? this.primary.freshResumeReport(now) : null; }
+  cancelSuspend(rec) { return this.primary ? this.primary.cancelSuspend(rec) : false; }
+
   inputReply(cmd, rec) {
     const waiting = [...this.planes.values()].find((p) => p.engine && p.inputWaiting);
     if (waiting) return waiting.inputReply(cmd, rec);

package/host/engine-r.mjs

@@ -82,6 +82,11 @@ export function detectRBinary(rscript) {
 }
 
 /** One R worker process. */
+/** readline's screen width for the interactive worker (see spawnPlan). */
+export const READLINE_COLUMNS = 100000;
+/** First on the boot line: give user code back the COLUMNS it started with (or none). */
+export const R_WIDTH_BOOT = 'local({ cols <- Sys.getenv("CARMAR_USER_COLUMNS"); Sys.unsetenv("CARMAR_USER_COLUMNS"); if (nzchar(cols)) Sys.setenv(COLUMNS = cols) else Sys.unsetenv("COLUMNS") }); ';
+
 export class REngine extends StdioEngine {
   /**
    * @param {Object} opts
@@ -105,6 +110,7 @@ export class REngine extends StdioEngine {
     if (!workerPath || !fs.existsSync(workerPath)) throw new Error(`REngine: no worker at ${workerPath}`);
     if (!rscript) throw new Error("REngine: no Rscript found (set CARMAR_RSCRIPT)");
     this.rscript = rscript;
+    this.userColumns = processEnv.COLUMNS == null ? "" : String(processEnv.COLUMNS);
     // Windows: Rterm.exe --ess is the interactive worker (host/windows-runtime.mjs).
     // CARMAR_WIN_BATCH=1 keeps the old batch worker, as an escape hatch should
     // some R build refuse --ess with a piped stdin.
@@ -138,18 +144,19 @@ export class REngine extends StdioEngine {
         // --no-echo suppresses the "> " prompt; the echo it does not suppress
         // is scrubbed by LineFramer through the cmdtag.
         //
-        // --no-readline FIRST. With readline, R echoes every line it reads back
-        // on stdout — and on Linux (R 4.3.3, 2026-09-16) readline's horizontal
-        // scrolling redraws a long command line as "<" + its tail, which no
-        // longer carries the cmdtag, so the echo leaked into chunk output
-        // (`beatrina check` on .39 read it as "the line after Stop ran").
-        // R honours --no-readline only BEFORE --interactive: after it, the flag
-        // is ignored and capabilities("cledit") stays TRUE (measured on Linux
-        // R 4.3.3 and macOS R 4.5.2). Without readline R reads plain lines,
-        // echoes nothing, and readline()/browser() still read the console.
-        // test/r-echo.test.mjs pins both the order and the silence.
-        args: ["--no-readline", "--interactive", "--no-echo", "--no-save", "--no-restore", "--no-site-file"],
-        env: { CARMAR_WORKER_MODE: "interactive" },
+        // COLUMNS is readline's screen width when there is no terminal. At the
+        // default 80, readline's horizontal scrolling redraws a long command
+        // line as "<" + its tail — which carries no cmdtag, so on Linux (R 4.3.3,
+        // `beatrina check`, 2026-09-16) fragments of the wire command leaked into
+        // chunk output. A width no line reaches keeps the echo whole, tag and
+        // all, and the scrub drops it. It is readline's width only: the boot
+        // line restores the user's COLUMNS before any user code (R_WIDTH_BOOT),
+        // and getOption("width") never read it. --no-readline was the first fix
+        // and is WRONG: without readline R reads the console with stdio fgets,
+        // and a Stop at an idle prompt left the stream in error — test:aicoding
+        // and test:sessionrecovery hung. test/r-echo.test.mjs pins both.
+        args: ["--interactive", "--no-echo", "--no-save", "--no-restore", "--no-site-file"],
+        env: { CARMAR_WORKER_MODE: "interactive", COLUMNS: String(READLINE_COLUMNS), CARMAR_USER_COLUMNS: this.userColumns },
       };
     }
     return {
@@ -174,7 +181,7 @@ export class REngine extends StdioEngine {
     const attach = handoff
       ? `local({ e <- attach(NULL, name = "beatrix:handoff", warn.conflicts = FALSE); sys.source(${JSON.stringify(handoff)}, envir = e, keep.source = FALSE) }); `
       : "";
-    this.rawLine(`${attach}sys.source(${JSON.stringify(worker)}, envir = globalenv(), keep.source = FALSE)`);
+    this.rawLine(`${R_WIDTH_BOOT}${attach}sys.source(${JSON.stringify(worker)}, envir = globalenv(), keep.source = FALSE)`);
   }
 
   /** engines/r/handoff.R for this host, or "" when this build has none. */

package/host/engine-stdio.mjs

@@ -91,8 +91,10 @@ export function engineEnvironment({ sentinel, cmdtag, workerDir, extra = {}, bas
  * is our own command echoed back (kept only for the text before the tag).
  */
 export class LineFramer {
-  constructor({ sentinel, cmdtag, channel }) {
+  constructor({ sentinel, cmdtag, channel, isEcho = null }) {
     this.sentinel = sentinel;
+    // A raw console line the host itself wrote, echoed back whole by R's readline (Linux): not output.
+    this.isEcho = typeof isEcho === "function" ? isEcho : null;
     this.tag = cmdtag ? `#${cmdtag}` : null;
     this.channel = channel;        // "stdout" | "stderr"
     this.tail = "";
@@ -121,6 +123,7 @@ export class LineFramer {
         const at = line.indexOf(this.tag);
         if (at >= 0) { line = line.slice(0, at); if (!line) continue; }
       }
+      if (this.isEcho && this.isEcho(line)) continue;
       const at = line.indexOf(this.sentinel);
       if (at < 0) { plain.push(line); continue; }
       const prefix = line.slice(0, at);
@@ -241,7 +244,9 @@ export class StdioEngine extends EventEmitter {
     });
     this.alive = true;
     this.pid = this.proc.pid;
-    const out = new LineFramer({ sentinel: this.sentinel, cmdtag: this.cmdtag, channel: "stdout" });
+    // The boot line (and any raw console line) carries no command tag; readline echoes it whole.
+    this.recentRaw = [];
+    const out = new LineFramer({ sentinel: this.sentinel, cmdtag: this.cmdtag, channel: "stdout", isEcho: (l) => l.length > 40 && this.recentRaw.includes(l) });
     const err = new LineFramer({ sentinel: this.sentinel, cmdtag: null, channel: "stderr" });
     this.proc.stdout.setEncoding("utf8");
     this.proc.stderr.setEncoding("utf8");
@@ -265,6 +270,9 @@ export class StdioEngine extends EventEmitter {
   /** One RAW line on stdin, with no command framing. */
   rawLine(line) {
     if (/\n/.test(line)) throw new Error("StdioEngine.rawLine: one line, no newline");
+    // Remembered so an exact echo of it is not shown as output (LineFramer isEcho). Only lines long
+    // enough to be ours are matched: a short readline answer echoed as "Q? yes" is the user's own text.
+    this.recentRaw = [...(this.recentRaw || []), line].slice(-8);
     return this.write(`${line}\n`);
   }
 

package/host/main.mjs

@@ -40,6 +40,7 @@ import { PythonEngine, detectPython } from "./engine-python.mjs";
 import { JsEngine, detectNode } from "./engine-js.mjs";
 import { EnginePool } from "./engine-pool.mjs";
 import { createHostServer, secureToken } from "./server.mjs";
+import { decodeSessionDocuments, keepTokenOk, sessionDocumentsLabel } from "./session-keep.mjs";
 import { createSettings } from "./settings.mjs";
 // ── planes (one line per family; see the seam in server.mjs) ───────────────
 // Each work package registers its module here and nowhere else. Keep the
@@ -346,6 +347,9 @@ async function main() {
       host: "beatrix",
     }),
   });
+  // Set before the worker starts, so its first ready frame cannot arrive ahead of the token.
+  if (keepTokenOk(env("CARMAR_RESUME_TOKEN"))) plane.setResumePending(env("CARMAR_RESUME_TOKEN"));
+  delete process.env.CARMAR_RESUME_TOKEN;
   await plane.start();
 
   // ── the server ─────────────────────────────────────────────────────────────
@@ -361,6 +365,12 @@ async function main() {
   // A successor started by a handoff keeps the session's name.
   const inheritedTitle = env("CARMAR_SESSION_TITLE").trim();
   if (inheritedTitle) runtimeRecord.title = inheritedTitle.slice(0, 120);
+  // A handoff successor starts with its predecessor's documents and, for "Restart, keep variables", the
+  // token its first worker restores (host/session-keep.mjs). Only a token travels, never a path.
+  const inheritedDocuments = decodeSessionDocuments(env("CARMAR_SESSION_DOCUMENTS"));
+  delete process.env.CARMAR_SESSION_DOCUMENTS;
+  if (sessionDocumentsLabel(inheritedDocuments)) runtimeRecord.documents = sessionDocumentsLabel(inheritedDocuments);
+
   const handoffFrom = env("CARMAR_HANDOFF_FROM").trim();
   const writeRuntime = () => {
     if (!runtimeFile) return false;
@@ -396,6 +406,14 @@ async function main() {
     notebookPage: (build) => notebookPage(build, { fallback: false }), notebookFileUrl: (p, prt, cap) => notebookFileUrl(path.resolve(p), prt, cap),
     runtimeRecord: () => runtimeRecord, handoffFrom,
     pendingOpen: env("CARMAR_OPEN_FILE") || null,
+    sessionDocuments: inheritedDocuments,
+    // The menu helper names a session by its document ("SezerProfiles.qmd + 1 more").
+    onSessionDocuments: (documents) => {
+      const label = sessionDocumentsLabel(documents);
+      if ((runtimeRecord.documents || "") === label) return;
+      if (label) runtimeRecord.documents = label; else delete runtimeRecord.documents;
+      writeRuntime();
+    },
     onShutdown: (reason) => shutdown(reason || "explicit Quit request"),
     onPageTitle: (title) => {
       // eslint-disable-next-line no-control-regex
@@ -441,10 +459,16 @@ async function main() {
   audit("started", { port: boundPort, root: env("CARMAR_ROOT") });
   process.stdout.write(`${JSON.stringify({ url, file: fileUrl })}\n`);
   // --open: open the notebook FILE, as serve.R did for the double-click
-  // launchers. The kernel stays hidden plumbing. CARMAR_OPENER is the seam a
-  // test uses so nothing opens on a real desktop.
-  if (process.argv.slice(2).includes("--open")) {
-    const target = fileUrl || url;
+  // launchers. --open=url opens the page THIS kernel serves instead
+  // (http://127.0.0.1:<port>/): the one origin the socket allows outright, so
+  // the page connects with no fragment and no pairing. The `beatrina` command
+  // uses it, because macOS `open` and Finder drop a file URL's #kernel=…&pair=…
+  // fragment and the page then cannot find its kernel ("needs R", 2026-09-16).
+  // The kernel stays hidden plumbing. CARMAR_OPENER is the seam a test uses so
+  // nothing opens on a real desktop.
+  const openArg = process.argv.slice(2).find((a) => a === "--open" || a === "--open=url" || a === "--open=file");
+  if (openArg) {
+    const target = openArg === "--open=url" ? url : (fileUrl || url);
     const opener = String(process.env.CARMAR_OPENER || "");
     try {
       const child = path.isAbsolute(opener) ? spawn(opener, [target], { stdio: "ignore", detached: true })

package/host/planes/latex.mjs

@@ -124,6 +124,32 @@ export function latexPreviewInline(html, dir) {
 }
 
 /** Render one LaTeX source to HTML for the preview pane. */
+/**
+ * Highlighted code blocks as plain verbatim, for the PREVIEW only — the host's twin of spike/latex.R
+ * latex_preview_code() (CarmaR 0.8.6), rule for rule.
+ *
+ * The export writes R chunks as fancyvrb `Highlighting` blocks (lib/md/latex.js), correct for a TeX
+ * engine, but pandoc's LaTeX reader does not know that environment is verbatim and rendered each block
+ * as an EMPTY div: the preview showed a document with its code missing while the PDF was right. Each
+ * block becomes `\begin{verbatim}` with the token macros dropped and lib/md/latex.js CODE_CH undone.
+ * Escapes become sentinels BEFORE the macro braces are stripped, so a literal `{` survives; a code line
+ * holding `\end{verbatim}` gains a zero-width space after the backslash. The file on disk and the
+ * compile are untouched. Pinned by test/latex-preview-code.test.mjs, against a real pandoc.
+ */
+const PREVIEW_CODE_BLOCK = /(?:\\begin\{Shaded\}[ \t]*\n?)?\\begin\{Highlighting\}(?:\[[^\]\n]*\])?\n?([\s\S]*?)\n?\\end\{Highlighting\}(?:[ \t]*\n?\\end\{Shaded\})?/g;
+const PREVIEW_CODE_SWAPS = [["\\textbackslash{}", "\u0001"], ["\\textasciitilde{}", "~"], ["\\^{}", "^"], ["\\textless{}", "<"], ["\\textgreater{}", ">"],
+  ["{-}", "-"], ["\\{", "\u0002"], ["\\}", "\u0003"], ["\\#", "#"], ["\\%", "%"], ["\\_", "_"], ["\\&", "&"]];
+export function latexPreviewCode(source) {
+  if (typeof source !== "string") return source;
+  return source.replace(PREVIEW_CODE_BLOCK, (_, inner) => {
+    let body = PREVIEW_CODE_SWAPS.reduce((text, [from, to]) => text.split(from).join(to), inner);
+    body = body.replace(/\\[A-Za-z]+Tok\{/g, "").replace(/[{}]/g, "");
+    body = body.replace(/\u0001/g, "\\").replace(/\u0002/g, "{").replace(/\u0003/g, "}");
+    body = body.split("\\end{verbatim}").join("\\\u200bend{verbatim}");
+    return `\\begin{verbatim}\n${body}\n\\end{verbatim}`;
+  });
+}
+
 export async function latexPreview(source, docPath, buffers, { pandoc, timeoutMs = LATEX_PREVIEW_TIMEOUT_MS } = {}) {
   if (!scalar(source) || source.length === 0) return { ok: false, error: "No LaTeX source to preview." };
   if (bytes(source) > LATEX_PREVIEW_MAX_SOURCE) return { ok: false, error: "This document is too large to preview while you type." };
@@ -135,7 +161,7 @@ export async function latexPreview(source, docPath, buffers, { pandoc, timeoutMs
   if (buffers && typeof buffers === "object" && !Array.isArray(buffers)) {
     Object.keys(buffers).filter(Boolean).slice(0, LATEX_PREVIEW_MAX_FILES).forEach((k) => { if (typeof buffers[k] === "string") keep[k] = buffers[k]; });
   }
-  const expanded = dir ? latexPreviewExpand(source, dir, keep) : source;
+  const expanded = latexPreviewCode(dir ? latexPreviewExpand(source, dir, keep) : source);
   const started = process.hrtime.bigint();
   const args = ["--from=latex", "--to=html5", "--mathml", "--wrap=none", "--standalone", "--sandbox"];
   if (dir) latexPreviewBibliography(expanded, dir).forEach((bib) => args.push("--citeproc", `--bibliography=${bib}`));