npm - beatrina - Versions diffs - 0.8.6 - Mend

beatrina 0.8.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (114) hide show

package/LICENSE +92 -0
package/NOTICES +72 -0
package/README.md +124 -0
package/bin/beatrina.mjs +223 -0
package/bin/cli.mjs +80 -0
package/bin/failsafe.mjs +74 -0
package/bin/identity.mjs +45 -0
package/bin/prova-post.mjs +51 -0
package/bin/sessions.mjs +95 -0
package/bin/shortcut.mjs +151 -0
package/bin/update-check.mjs +55 -0
package/bin/upgrade.mjs +76 -0
package/build-info.json +1 -0
package/carmar_V0.8.6.html +1310 -0
package/check/acceptance.mjs +278 -0
package/check/session.mjs +215 -0
package/engines/js/document-exec.mjs +82 -0
package/engines/js/persist.mjs +214 -0
package/engines/js/worker.mjs +424 -0
package/engines/python/adapter.py +577 -0
package/engines/python/analyze.py +814 -0
package/engines/python/bootstrap.py +309 -0
package/engines/python/dataview.py +735 -0
package/engines/python/debugger.py +346 -0
package/engines/python/document_exec.py +158 -0
package/engines/python/engine.json +28 -0
package/engines/python/handoff.py +118 -0
package/engines/python/worker.py +564 -0
package/engines/r/engine.json +25 -0
package/engines/r/handoff.R +92 -0
package/failsafe/ai-policy.R +255 -0
package/failsafe/ai-store.R +373 -0
package/failsafe/cite.R +418 -0
package/failsafe/journal.R +684 -0
package/failsafe/plugins.R +809 -0
package/failsafe/serve.R +5500 -0
package/host/ai-policy.mjs +218 -0
package/host/deployment.mjs +160 -0
package/host/engine-js.mjs +98 -0
package/host/engine-pool.mjs +383 -0
package/host/engine-python.mjs +228 -0
package/host/engine-r.mjs +206 -0
package/host/engine-stdio.mjs +401 -0
package/host/journal-store.mjs +749 -0
package/host/main.mjs +503 -0
package/host/planes/README.md +41 -0
package/host/planes/ai-store.mjs +327 -0
package/host/planes/ai.mjs +467 -0
package/host/planes/analyze.mjs +397 -0
package/host/planes/cite.mjs +517 -0
package/host/planes/files.mjs +0 -0
package/host/planes/jobs.mjs +704 -0
package/host/planes/journal.mjs +53 -0
package/host/planes/latex.mjs +201 -0
package/host/planes/mcp.mjs +493 -0
package/host/planes/pair.mjs +325 -0
package/host/planes/pipe-term.mjs +122 -0
package/host/planes/plugins.mjs +112 -0
package/host/planes/proc-tree.mjs +76 -0
package/host/planes/sessions.mjs +434 -0
package/host/planes/settings.mjs +164 -0
package/host/planes/terminal.mjs +286 -0
package/host/planes/test-file.mjs +80 -0
package/host/planes/update.mjs +214 -0
package/host/plugin-store.mjs +838 -0
package/host/server.mjs +441 -0
package/host/settings.mjs +379 -0
package/host/update-record.mjs +59 -0
package/host/user-dirs.mjs +117 -0
package/host/windows-runtime.mjs +145 -0
package/host/worker-plane.mjs +713 -0
package/host/ws.mjs +190 -0
package/kernel/analyze.R +668 -0
package/kernel/deployment.R +165 -0
package/kernel/examples/NOTICE.md +38 -0
package/kernel/examples/tna-complete-tutorial.Rmd +210 -0
package/kernel/fileio.R +656 -0
package/kernel/index.html +96 -0
package/kernel/job-run.R +391 -0
package/kernel/jobs.R +276 -0
package/kernel/kernel-protocol +1 -0
package/kernel/kernel-version +1 -0
package/kernel/kernel.R +671 -0
package/kernel/knitr-run.R +245 -0
package/kernel/latex.R +609 -0
package/kernel/mcp/carmar-mcp.mjs +516 -0
package/kernel/notebook-page.R +67 -0
package/kernel/plugins/csl/apa/apa.csl +2273 -0
package/kernel/plugins/csl/apa/plugin.json +19 -0
package/kernel/plugins/csl/chicago-author-date/chicago-author-date.csl +4216 -0
package/kernel/plugins/csl/chicago-author-date/plugin.json +19 -0
package/kernel/plugins/csl/harvard-cite-them-right/harvard-cite-them-right.csl +316 -0
package/kernel/plugins/csl/harvard-cite-them-right/plugin.json +19 -0
package/kernel/plugins/csl/ieee/ieee.csl +519 -0
package/kernel/plugins/csl/ieee/plugin.json +19 -0
package/kernel/plugins/csl/modern-language-association/modern-language-association.csl +1184 -0
package/kernel/plugins/csl/modern-language-association/plugin.json +19 -0
package/kernel/plugins/csl/nature/nature.csl +189 -0
package/kernel/plugins/csl/nature/plugin.json +19 -0
package/kernel/plugins/latex/apa7/apa7.json +14 -0
package/kernel/plugins/latex/apa7/plugin.json +19 -0
package/kernel/plugins/latex/elsarticle/elsarticle.json +14 -0
package/kernel/plugins/latex/elsarticle/plugin.json +19 -0
package/kernel/plugins/latex/ieeetran/ieeetran.json +10 -0
package/kernel/plugins/latex/ieeetran/plugin.json +19 -0
package/kernel/project.R +131 -0
package/kernel/settings.R +410 -0
package/kernel/sniff.R +769 -0
package/kernel/worker-boot.R +22 -0
package/kernel/worker.R +3496 -0
package/lib/agent-authoring-contract.js +547 -0
package/lib/cell-kinds.js +108 -0
package/lib/engine-labels.js +324 -0
package/package.json +32 -0

package/kernel/index.html ADDED Viewed

@@ -0,0 +1,96 @@
+<!doctype html>
+<meta charset="utf-8">
+<title>CarmaR kernel spike</title>
+<style>
+  :root { color-scheme: light dark; }
+  body { font: 14px/1.5 ui-sans-serif, system-ui, sans-serif; margin: 0; padding: 1.5rem;
+         max-width: 60rem; }
+  h1 { font-size: 1rem; font-weight: 600; margin: 0 0 1rem; letter-spacing: .01em; }
+  #status { font-variant-numeric: tabular-nums; opacity: .7; font-size: .85rem; }
+  textarea { width: 100%; min-height: 7rem; font: 13px/1.5 ui-monospace, monospace;
+             padding: .6rem; box-sizing: border-box; }
+  .row { display: flex; gap: .5rem; margin: .6rem 0; align-items: center; }
+  button { font: inherit; padding: .35rem .9rem; }
+  pre { font: 12px/1.5 ui-monospace, monospace; padding: .8rem; margin: 0;
+        background: color-mix(in srgb, currentColor 6%, transparent);
+        border-radius: 4px; max-height: 26rem; overflow: auto; white-space: pre-wrap; }
+  .stderr, .warning { color: #b45309; }
+  .error { color: #b91c1c; }
+  .meta { opacity: .55; }
+  table { border-collapse: collapse; margin: .5rem 0; font-size: 12px; display: block;
+          overflow-x: auto; max-width: 100%; }
+  th, td { border: 1px solid color-mix(in srgb, currentColor 20%, transparent);
+           padding: .15rem .5rem; text-align: left; white-space: nowrap; }
+  th { font-weight: 600; opacity: .8; }
+  img { display: block; margin: .5rem 0; border-radius: 3px; }
+</style>
+<h1>CarmaR kernel spike <span id="status">connecting…</span></h1>
+<textarea id="src">for (i in 1:20) { cat("tick", i, "\n"); flush(stdout()); Sys.sleep(0.5) }</textarea>
+<div class="row">
+  <button id="run">Run</button>
+  <button id="stop">Stop</button>
+  <span class="meta">Stop sends SIGINT to the worker — the session survives.</span>
+</div>
+<pre id="out"></pre>
+<script>
+  const params = new URLSearchParams(location.search);
+  const ws = new WebSocket(`ws://${location.host}/ws`);
+  const out = document.getElementById('out');
+  const status = document.getElementById('status');
+  let n = 0;
+  const write = (text, cls) => {
+    const span = document.createElement('span');
+    if (cls) span.className = cls;
+    span.textContent = text + '\n';
+    out.appendChild(span);
+    out.scrollTop = out.scrollHeight;
+  };
+  ws.onopen = () => { status.textContent = 'connected'; };
+  ws.onclose = () => { status.textContent = 'disconnected'; };
+  ws.onmessage = (ev) => {
+    const msg = JSON.parse(ev.data);
+    if (msg.type === 'ready') status.textContent = `ready — ${msg.r} (pid ${msg.pid})`;
+    else if (msg.type === 'stdout') write(msg.text);
+    else if (msg.type === 'stderr') write(msg.text, 'stderr');
+    else if (msg.type === 'stream') write(`${msg.kind}: ${msg.text}`, msg.kind);
+    else if (msg.type === 'plot') {
+      const img = new Image();
+      img.src = `data:${msg.mime};base64,${msg.data}`;
+      img.style.maxWidth = '100%';
+      out.appendChild(img);
+    }
+    else if (msg.type === 'dataframe') {
+      const table = document.createElement('table');
+      const head = table.insertRow();
+      msg.columns.forEach((c, i) => {
+        const th = document.createElement('th');
+        th.textContent = `${c} (${msg.types[i]})`;
+        head.appendChild(th);
+      });
+      const rows = Array.isArray(msg.rows) ? msg.rows : [msg.rows];
+      rows.slice(0, 20).forEach((r) => {
+        const tr = table.insertRow();
+        msg.columns.forEach((c) => { tr.insertCell().textContent = r[c]; });
+      });
+      out.appendChild(table);
+      write(`${msg.nrow} × ${msg.ncol}${msg.truncated ? ` — showing first ${rows.length}` : ''}`, 'meta');
+    }
+    else if (msg.type === 'done') write(`— ${msg.status}${msg.message ? ': ' + msg.message : ''}`,
+                                        msg.status === 'ok' ? 'meta' : 'error');
+    else if (msg.type === 'worker-died') status.textContent = 'worker died';
+  };
+  document.getElementById('run').onclick = () => {
+    ws.send(JSON.stringify({ type: 'exec', id: `c${++n}`, source: document.getElementById('src').value }));
+  };
+  document.getElementById('stop').onclick = () => {
+    ws.send(JSON.stringify({ type: 'interrupt' }));
+  };
+</script>

package/kernel/job-run.R ADDED Viewed

@@ -0,0 +1,391 @@
+#!/usr/bin/env Rscript
+#
+# job-run.R — one development task, in its own R process.
+#
+# Spawned by the supervisor through the ordinary `kernel_start()` path, so it
+# inherits the things that took a while to get right there: a UTF-8 child
+# locale whatever the launcher had, an R environment scrubbed of the
+# supervisor's own R_HOME/R_LIBS (which otherwise aim the child at the wrong
+# tree), and `kernel_poll`'s bounded drain, so a check that prints a megabyte
+# cannot starve the event loop.
+#
+# ── this process evaluates; that is the point, and the boundary ───────────
+#
+# analyze.R may never evaluate user source, because a second evaluating
+# session would have no Stop button and no session identity. This one may,
+# and has neither problem, because it is NOT a session: it is one task, it
+# owns no workspace anybody can see, it is killed by PID, and when it dies
+# nothing the user typed goes with it. `devtools::check()` is going to
+# evaluate the package's code no matter which process asks; the decision here
+# is only that the process is not the one holding the notebook's variables.
+#
+# ── nothing from the wire is parsed ───────────────────────────────────────
+#
+# The task name arrives in the environment and is matched against a `switch`
+# whose branches are literal calls. The root and the filter are passed as
+# ARGUMENTS to those calls, never pasted into an expression. There is no
+# `parse(text=)`, no `eval(parse(...))`, and none may be added — the same
+# rule analyze.R carries, for a different reason: there, so nothing runs;
+# here, so only the six things named below can.
+args <- commandArgs(trailingOnly = TRUE)
+sentinel <- args[1]
+if (is.na(sentinel) || !nzchar(sentinel)) {
+  stop("job-run.R needs a sentinel argument", call. = FALSE)
+}
+suppressPackageStartupMessages(library(jsonlite))
+here <- dirname(normalizePath(sub("^--file=", "", grep("^--file=", commandArgs(FALSE), value = TRUE)[1L])))
+source(file.path(here, "kernel.R"))
+source(file.path(here, "jobs.R"))
+source(file.path(here, "latex.R"))
+compile_identity <- NULL
+#' Write one control frame: the session's random sentinel, then compact JSON.
+#' Identical framing to worker.R and analyze.R, so kernel_poll needs no new case.
+#'
+#' The job's own id is stamped HERE rather than added by the supervisor on the
+#' way past, and that is a deliberate consequence of the frame-fidelity rule:
+#' a frame the supervisor has to rewrite is a frame it has to re-encode, and
+#' jsonlite's defaults round numbers to four digits, render an absent field as
+#' a truthy `{}` and collapse a one-element array to a scalar. A frame that
+#' already carries its id can be forwarded as BYTES.
+#'
+#' @param obj A list to serialise.
+#' @return Invisibly NULL.
+emit <- function(obj) {
+  frame <- c(list(type = obj$type, id = job_id), compile_identity, obj[setdiff(names(obj), "type")])
+  cat(sentinel, toJSON(frame, auto_unbox = TRUE, null = "null", na = "null", digits = NA), "\n", sep = "")
+  flush(stdout())
+  invisible(NULL)
+}
+job_id <- Sys.getenv("CARMAR_JOB_ID", "job")
+task   <- Sys.getenv("CARMAR_JOB_TASK", "")
+root   <- Sys.getenv("CARMAR_JOB_ROOT", "")
+target <- Sys.getenv("CARMAR_JOB_TARGET", "")
+filter <- Sys.getenv("CARMAR_JOB_FILTER", "")
+format <- Sys.getenv("CARMAR_JOB_FORMAT", "")
+# The supervisor validated all of this in jobs.R before spawning. Re-checking
+# here is not redundant: this file is also runnable by hand, and a task that
+# trusted its environment would be a very quiet way to run the wrong thing.
+KNOWN <- names(JOB_TASKS)
+if (!task %in% KNOWN) {
+  emit(list(type = "job", event = "done", ok = FALSE,
+            error = sprintf("unknown task '%s'", task)))
+  quit(status = 2L, save = "no")
+}
+if (!nzchar(root) || !dir.exists(root)) {
+  emit(list(type = "job", event = "done", ok = FALSE,
+            error = sprintf("'%s' is not a folder", root)))
+  quit(status = 2L, save = "no")
+}
+# A render acts on a FILE. Checking only the folder would let a task start
+# against a document that is not there and fail somewhere less legible.
+if (task %in% c("render", "latex") && (!nzchar(target) || !file.exists(target))) {
+  emit(list(type = "job", event = "done", ok = FALSE,
+            error = sprintf("'%s' is not a file", target)))
+  quit(status = 2L, save = "no")
+}
+if (identical(task, "latex")) {
+  prepared <- tryCatch({
+    identity_text <- Sys.getenv("CARMAR_LATEX_IDENTITY", "")
+    identity <- if (nzchar(identity_text)) jsonlite::fromJSON(identity_text, simplifyVector = FALSE) else NULL
+    spec <- job_spec(task, target, list(engine = Sys.getenv("CARMAR_LATEX_ENGINE", "auto"),
+      timeout = suppressWarnings(as.numeric(Sys.getenv("CARMAR_LATEX_TIMEOUT", as.character(LATEX_TIMEOUT)))),
+      fetch = identical(Sys.getenv("CARMAR_LATEX_FETCH", ""), "1"), identity = identity))
+    if (!isTRUE(spec$ok)) stop(spec$error, call. = FALSE)
+    compile_identity <- identity
+    spec
+  }, error = function(e) e)
+  if (inherits(prepared, "error")) {
+    emit(list(type = "job", event = "done", ok = FALSE, error = conditionMessage(prepared)))
+    quit(status = 2L, save = "no")
+  }
+}
+#' Refuse early and in words when the task's package is missing.
+#' @param pkg Package name the task needs.
+#' @return Invisibly TRUE, or quits with a `done` frame.
+need <- function(pkg) {
+  if (requireNamespace(pkg, quietly = TRUE)) return(invisible(TRUE))
+  emit(list(type = "job", event = "done", ok = FALSE,
+            error = sprintf("this task needs the '%s' package, which is not installed. install.packages(\"%s\")",
+                            pkg, pkg)))
+  quit(status = 3L, save = "no")
+}
+# ── structured test results ────────────────────────────────────────────────
+#
+# The reason `test` gets its own extraction rather than a log the UI greps:
+# Stage 5's exit criterion is that a failure NAVIGATES to exact source, and a
+# regex over testthat's printed output cannot do that reliably — the format is
+# a reporter's presentation choice and changes between versions.
+#
+# Measured instead (testthat 3.3.2, against a synthetic package): every
+# expectation carries `$srcref`, an integer srcref whose first element is the
+# line and whose "srcfile" attribute holds the file name. Failures at lines
+# 2/6/10/14 of the fixture reported exactly 2/6/10/14. That is a field, not a
+# printed string, so it is what this reads.
+#' One expectation's status, from its class.
+#' @param e A testthat expectation condition.
+#' @return One of "success", "failure", "error", "skip", "warning".
+expectation_status <- function(e) {
+  cls <- class(e)
+  if (inherits(e, "expectation_success")) "success"
+  else if (inherits(e, "expectation_failure")) "failure"
+  else if (inherits(e, "expectation_error")) "error"
+  else if (inherits(e, "expectation_skip")) "skip"
+  else if (inherits(e, "expectation_warning")) "warning"
+  else sub("^expectation_", "", cls[[1L]])
+}
+# A failing suite can hold thousands of expectations, and every one of them
+# would ride the socket. Bounded — and the bound is REPORTED, because a list
+# that silently stops looks exactly like a suite that stopped failing.
+MAX_REPORTED <- 200L
+#' Flatten testthat's nested results into one tidy row per problem.
+#' @param results A `testthat_results` object.
+#' @return list(rows, counts, truncated)
+collect_results <- function(results) {
+  counts <- c(success = 0L, failure = 0L, error = 0L, skip = 0L, warning = 0L)
+  rows <- list()
+  # Nested lists of conditions: this walks blocks and their expectations. It
+  # is a loop rather than an apply because it accumulates into two different
+  # places (a tally and a bounded list) and stops adding to one of them.
+  for (block in results) {
+    for (e in block$results) {
+      status <- expectation_status(e)
+      if (status %in% names(counts)) counts[[status]] <- counts[[status]] + 1L
+      if (identical(status, "success")) next
+      if (length(rows) >= MAX_REPORTED) next
+      srcref <- e$srcref
+      line <- if (is.null(srcref)) NA_integer_ else as.integer(srcref)[1L]
+      file <- if (is.null(srcref)) NA_character_ else {
+        srcfile <- attr(srcref, "srcfile")
+        if (is.null(srcfile)) NA_character_ else (srcfile$filename %||% NA_character_)
+      }
+      name <- if (is.na(file)) (block$file %||% NA_character_) else basename(file)
+      # testthat's srcref carries only a BASENAME, and a basename is not
+      # something an editor can open. The full path is resolved here, where
+      # the filesystem actually is, and only when the file is really there —
+      # a path that does not exist is worse than none, because the UI would
+      # offer a link that opens an empty buffer.
+      full <- if (is.na(name)) NA_character_ else file.path(root, "tests", "testthat", name)
+      if (!is.na(full) && !file.exists(full)) full <- NA_character_
+      rows[[length(rows) + 1L]] <- list(
+        status = status,
+        test = block$test %||% NA_character_,
+        file = name,
+        path = full,
+        line = line,
+        message = paste(utils::head(strsplit(conditionMessage(e), "\n", fixed = TRUE)[[1L]], 12L),
+                        collapse = "\n")
+      )
+    }
+  }
+  problems <- sum(counts[c("failure", "error", "skip", "warning")])
+  list(rows = rows, counts = as.list(counts),
+       truncated = max(0L, problems - length(rows)))
+}
+run_tests <- function() {
+  need("testthat")
+  results <- testthat::test_local(
+    root,
+    filter = if (nzchar(filter)) filter else NULL,
+    reporter = "progress",
+    stop_on_failure = FALSE
+  )
+  collected <- collect_results(results)
+  emit(list(type = "job", event = "tests",
+            # I() so a single result stays an ARRAY on the wire. jsonlite
+            # collapses a length-1 list to a scalar otherwise, and the browser
+            # would iterate the characters of a string.
+            rows = I(collected$rows), counts = collected$counts,
+            truncated = collected$truncated,
+            root = root))
+  # A suite with failures is a completed job that found problems, not a job
+  # that failed to run. The distinction is the whole reason `ok` and the
+  # counts are separate fields.
+  invisible(collected)
+}
+# ── rendering a document ───────────────────────────────────────────────────
+#
+# ── finding quarto is the whole problem, and it is not `Sys.which` ────────
+#
+# Measured on a normal macOS machine with RStudio installed: `quarto` is NOT
+# on PATH, `quarto::quarto_path()` returns NULL, and a perfectly good Quarto
+# 1.9.37 sits inside RStudio.app. A renderer that asked PATH would have told
+# that user Quarto was not installed while it was on their disk and working.
+#
+# So this is a ladder, in the same spirit as detect_rscript() in kernel.R:
+# an explicit override, then what RStudio itself sets, then the R package's
+# own answer, then PATH, then the bundles we know about by name.
+#' Locate a quarto binary.
+#' @return Path to quarto, or "" when there is none.
+find_quarto <- function() {
+  explicit <- Sys.getenv("CARMAR_QUARTO", "")
+  if (nzchar(explicit) && file.exists(explicit)) return(explicit)
+  # RStudio and Positron both export this into the sessions they start.
+  from_env <- Sys.getenv("QUARTO_PATH", "")
+  if (nzchar(from_env) && file.exists(from_env)) return(from_env)
+  if (requireNamespace("quarto", quietly = TRUE)) {
+    found <- tryCatch(quarto::quarto_path(), error = function(e) NULL)
+    if (!is.null(found) && nzchar(found) && file.exists(found)) return(found)
+  }
+  on_path <- unname(Sys.which("quarto"))
+  if (nzchar(on_path)) return(on_path)
+  bundles <- c(
+    "/Applications/RStudio.app/Contents/Resources/app/quarto/bin/quarto",
+    "/Applications/Positron.app/Contents/Resources/app/quarto/bin/quarto",
+    "/usr/local/bin/quarto", "/opt/homebrew/bin/quarto",
+    "C:/Program Files/RStudio/resources/app/bin/quarto/bin/quarto.exe",
+    "C:/Program Files/Quarto/bin/quarto.exe"
+  )
+  hit <- Find(file.exists, bundles)
+  if (is.null(hit)) "" else hit
+}
+#' Which renderer for this document?
+#'
+#' `.qmd` is Quarto's format and rmarkdown cannot read it, so there is no
+#' choice to make. `.Rmd` and `.md` go to rmarkdown when it is installed —
+#' Quarto renders them too, but with Quarto's semantics, and silently
+#' changing how someone's existing .Rmd builds is not an improvement the
+#' reader asked for.
+#'
+#' @param path The document.
+#' @return "quarto" or "rmarkdown".
+pick_renderer <- function(path) {
+  ext <- tolower(sub("^.*\\.", "", basename(path)))
+  if (identical(ext, "qmd")) return("quarto")
+  if (requireNamespace("rmarkdown", quietly = TRUE)) "rmarkdown" else "quarto"
+}
+#' Run a command, streaming its output live AND keeping it.
+#'
+#' `system2(stdout = "")` streams but keeps nothing; `system2(stdout = TRUE)`
+#' keeps everything but delivers it only at the end — and a render is exactly
+#' the case where a reader wants to watch. Polling processx gives both, which
+#' matters because quarto reports where it put the file on a line of ordinary
+#' output rather than in an exit code.
+#'
+#' @param bin Executable.
+#' @param args Character vector of arguments — an argument VECTOR, never a
+#'   shell string, so a path with a space or a quote in it is one argument.
+#' @return list(status, lines)
+run_streaming <- function(bin, args, wd = NULL, timeout = Inf, env = NULL) {
+  proc <- processx::process$new(bin, args, wd = wd, env = env, stdout = "|", stderr = "2>&1", supervise = TRUE, encoding = "UTF-8")
+  on.exit(kernel_kill_tree(list(proc = proc)), add = TRUE)
+  kept <- ""; truncated <- FALSE; timed_out <- FALSE; started_at <- Sys.time()
+  keep <- function(text) {
+    if (!nzchar(text)) return(invisible(NULL))
+    cat(text, sep = ""); flush(stdout())
+    kept <<- paste0(kept, text)
+    if (nchar(kept) > 1000000L) { kept <<- substring(kept, nchar(kept) - 999999L); truncated <<- TRUE }
+  }
+  repeat {
+    proc$poll_io(100L)
+    keep(proc$read_output(65536L))
+    if (as.numeric(difftime(Sys.time(), started_at, units = "secs")) >= timeout) { timed_out <- TRUE; break }
+    if (!proc$is_alive()) {
+      repeat {
+        proc$poll_io(0L)
+        leftover <- proc$read_output(65536L)
+        keep(leftover)
+        if (!nzchar(leftover)) break
+      }
+      break
+    }
+  }
+  list(status = if (timed_out) NA_integer_ else proc$get_exit_status(),
+    lines = strsplit(kept, "\n", fixed = TRUE)[[1L]], timed_out = timed_out, truncated = truncated)
+}
+#' Render one document, and report where the output actually went.
+#'
+#' The output path is REPORTED, never guessed. rmarkdown::render returns an
+#' absolute path (measured). Quarto prints "Output created: <path>", relative
+#' to the document's own directory — also measured, including the case that
+#' matters: rendering a full path from an unrelated working directory still
+#' puts the output beside the source and still reports it relatively. Either
+#' way the file is checked to exist before it is reported, for the same
+#' reason a test failure only offers a link to a file that is really there.
+render_document <- function() {
+  renderer <- pick_renderer(target)
+  produced <- NA_character_
+  if (identical(renderer, "rmarkdown")) {
+    need("rmarkdown")
+    out <- rmarkdown::render(
+      target,
+      output_format = if (nzchar(format)) format else NULL,
+      knit_root_dir = dirname(target)
+    )
+    if (length(out) >= 1L && nzchar(out[[1L]])) produced <- out[[1L]]
+  } else {
+    bin <- find_quarto()
+    if (!nzchar(bin)) {
+      stop("Quarto is not installed, or CarmaR could not find it. Install Quarto, ",
+           "or set CARMAR_QUARTO to the binary.", call. = FALSE)
+    }
+    args <- c("render", target)
+    if (nzchar(format)) args <- c(args, "--to", format)
+    result <- run_streaming(bin, args)
+    if (!identical(as.integer(result$status), 0L)) {
+      stop(sprintf("quarto render exited %s", result$status), call. = FALSE)
+    }
+    hits <- grep("^Output created:", trimws(result$lines), value = TRUE)
+    if (length(hits)) {
+      reported <- trimws(sub("^Output created:", "", trimws(hits[[length(hits)]])))
+      # Relative to the SOURCE directory, not this process's cwd.
+      candidate <- if (grepl("^(/|[A-Za-z]:)", reported)) reported
+                   else file.path(dirname(target), reported)
+      produced <- candidate
+    }
+  }
+  if (!is.na(produced) && file.exists(produced)) {
+    produced <- normalizePath(produced, mustWork = FALSE)
+  } else {
+    # It rendered but we could not confirm where. Saying nothing is right;
+    # naming a file that may not be there is not.
+    produced <- NA_character_
+  }
+  emit(list(type = "job", event = "output", renderer = renderer,
+            path = produced, format = if (nzchar(format)) format else NA_character_))
+  invisible(produced)
+}
+started <- Sys.time()
+emit(list(type = "job", event = "started", task = task, root = root, pid = Sys.getpid()))
+outcome <- tryCatch({
+  switch(task,
+    load     = { need("pkgload");  pkgload::load_all(root, quiet = FALSE); NULL },
+    document = { need("devtools"); devtools::document(root); NULL },
+    test     = run_tests(),
+    check    = { need("devtools"); devtools::check(root, quiet = FALSE); NULL },
+    build    = { need("devtools"); devtools::build(root); NULL },
+    install  = { need("devtools"); devtools::install(root, quick = TRUE, upgrade = "never"); NULL },
+    render   = render_document(),
+    latex    = latex_compile(target, prepared$env[["CARMAR_LATEX_ENGINE"]],
+      as.numeric(prepared$env[["CARMAR_LATEX_TIMEOUT"]]), job_id, run_streaming, emit,
+      fetch = identical(prepared$env[["CARMAR_LATEX_FETCH"]], "1"))
+  )
+  list(ok = TRUE, error = "")
+}, error = function(e) {
+  # Reported, never swallowed: the message is the job's result, and the
+  # non-zero exit below is what the supervisor's `done` frame carries.
+  list(ok = FALSE, error = conditionMessage(e))
+})
+emit(list(type = "job", event = "done", ok = isTRUE(outcome$ok),
+          error = outcome$error %||% "",
+          elapsed = round(as.numeric(difftime(Sys.time(), started, units = "secs")), 2)))
+quit(status = if (isTRUE(outcome$ok)) 0L else 1L, save = "no")