dsh-oc-tui 0.2.0 → 0.3.0

package/dsh-plugin.json

@@ -1,69 +1,69 @@
-{
-  "$schema": "https://raw.githubusercontent.com/Yan-Zero/dsh-std/main/packages/manifest/schema/dsh-plugin-0.15.schema.json",
-  "manifestVersion": "0.15",
-  "id": "io.github.rayafriandion.dsh-oc-tui",
-  "name": "dsh-oc-tui",
-  "version": "0.2.0",
-  "license": "LGPL-3.0-or-later",
-  "source": { "repository": "https://github.com/rayafriandion/dsh-oc-tui" },
-  "facets": { "host": { "entry": "lib/facet.js", "apiVersion": "v1alpha1" } },
-  "requires": {
-    "contracts": [
-      { "apiVersion": "commands.dsh/v1alpha1", "kind": "Command", "optional": true }
-    ]
-  },
-  "permissions": [
-    { "name": "storage.local.read", "scope": "io.github.rayafriandion.dsh-oc-tui",
-      "reason": "Read TUI settings from the host settings store." },
-    { "name": "storage.local.write", "scope": "io.github.rayafriandion.dsh-oc-tui",
-      "reason": "Persist TUI settings chosen in the Settings pages." }
-  ],
-  "contributes": {
-    "x-dev.dsh-std.extensions": [
-      { "id": "io.github.rayafriandion.dsh-oc-tui.settings",
-        "apiVersion": "commands.dsh/v1alpha1", "kind": "Command", "name": "settings",
-        "spec": { "title": "Open the TUI settings pages",
-                  "placements": [{ "apiVersion": "tui.dsh/v1alpha1", "kind": "CommandLine" }] } },
-      { "id": "io.github.rayafriandion.dsh-oc-tui.help",
-        "apiVersion": "commands.dsh/v1alpha1", "kind": "Command", "name": "help",
-        "spec": { "title": "Show the TUI key and command reference",
-                  "placements": [{ "apiVersion": "tui.dsh/v1alpha1", "kind": "CommandLine" }] } },
-      { "id": "io.github.rayafriandion.dsh-oc-tui.stats",
-        "apiVersion": "commands.dsh/v1alpha1", "kind": "Command", "name": "stats",
-        "spec": { "title": "Show session token and cache statistics",
-                  "placements": [{ "apiVersion": "tui.dsh/v1alpha1", "kind": "CommandLine" }] } },
-      { "id": "io.github.rayafriandion.dsh-oc-tui.new",
-        "apiVersion": "commands.dsh/v1alpha1", "kind": "Command", "name": "new",
-        "spec": { "title": "Start a new session",
-                  "placements": [{ "apiVersion": "tui.dsh/v1alpha1", "kind": "CommandLine" }] } },
-      { "id": "io.github.rayafriandion.dsh-oc-tui.resume",
-        "apiVersion": "commands.dsh/v1alpha1", "kind": "Command", "name": "resume",
-        "spec": { "title": "Resume a persisted session",
-                  "placements": [{ "apiVersion": "tui.dsh/v1alpha1", "kind": "CommandLine" }] } },
-      { "id": "io.github.rayafriandion.dsh-oc-tui.clear",
-        "apiVersion": "commands.dsh/v1alpha1", "kind": "Command", "name": "clear",
-        "spec": { "title": "Clear the transcript",
-                  "placements": [{ "apiVersion": "tui.dsh/v1alpha1", "kind": "CommandLine" }] } },
-      { "id": "io.github.rayafriandion.dsh-oc-tui.cancel",
-        "apiVersion": "commands.dsh/v1alpha1", "kind": "Command", "name": "cancel",
-        "spec": { "title": "Cancel the running turn",
-                  "placements": [{ "apiVersion": "tui.dsh/v1alpha1", "kind": "CommandLine" }] } },
-      { "id": "io.github.rayafriandion.dsh-oc-tui.rewind",
-        "apiVersion": "commands.dsh/v1alpha1", "kind": "Command", "name": "rewind",
-        "spec": { "title": "Rewind the session to an earlier point",
-                  "placements": [{ "apiVersion": "tui.dsh/v1alpha1", "kind": "CommandLine" }] } },
-      { "id": "io.github.rayafriandion.dsh-oc-tui.branch",
-        "apiVersion": "commands.dsh/v1alpha1", "kind": "Command", "name": "branch",
-        "spec": { "title": "Switch git branches on the empty page",
-                  "placements": [{ "apiVersion": "tui.dsh/v1alpha1", "kind": "CommandLine" }] } },
-      { "id": "io.github.rayafriandion.dsh-oc-tui.quit",
-        "apiVersion": "commands.dsh/v1alpha1", "kind": "Command", "name": "quit",
-        "spec": { "title": "Leave the TUI", "aliases": ["exit"],
-                  "placements": [{ "apiVersion": "tui.dsh/v1alpha1", "kind": "CommandLine" }] } }
-    ]
-  },
-  "overrides": [
-    { "target": "@deepseek-ai/dsh-base", "kind": "patch",
-      "description": "cordis.patch.yml inserts the tui-startup, tui-app, agent-presets and tool-ask-user rows." }
-  ]
-}
+{
+  "$schema": "https://raw.githubusercontent.com/Yan-Zero/dsh-std/main/packages/manifest/schema/dsh-plugin-0.15.schema.json",
+  "manifestVersion": "0.15",
+  "id": "io.github.rayafriandion.dsh-oc-tui",
+  "name": "dsh-oc-tui",
+  "version": "0.3.0",
+  "license": "LGPL-3.0-or-later",
+  "source": { "repository": "https://github.com/rayafriandion/dsh-oc-tui" },
+  "facets": { "host": { "entry": "lib/facet.js", "apiVersion": "v1alpha1" } },
+  "requires": {
+    "contracts": [
+      { "apiVersion": "commands.dsh/v1alpha1", "kind": "Command", "optional": true }
+    ]
+  },
+  "permissions": [
+    { "name": "storage.local.read", "scope": "io.github.rayafriandion.dsh-oc-tui",
+      "reason": "Read TUI settings from the host settings store." },
+    { "name": "storage.local.write", "scope": "io.github.rayafriandion.dsh-oc-tui",
+      "reason": "Persist TUI settings chosen in the Settings pages." }
+  ],
+  "contributes": {
+    "x-dev.dsh-std.extensions": [
+      { "id": "io.github.rayafriandion.dsh-oc-tui.settings",
+        "apiVersion": "commands.dsh/v1alpha1", "kind": "Command", "name": "settings",
+        "spec": { "title": "Open the TUI settings pages",
+                  "placements": [{ "apiVersion": "tui.dsh/v1alpha1", "kind": "CommandLine" }] } },
+      { "id": "io.github.rayafriandion.dsh-oc-tui.help",
+        "apiVersion": "commands.dsh/v1alpha1", "kind": "Command", "name": "help",
+        "spec": { "title": "Show the TUI key and command reference",
+                  "placements": [{ "apiVersion": "tui.dsh/v1alpha1", "kind": "CommandLine" }] } },
+      { "id": "io.github.rayafriandion.dsh-oc-tui.stats",
+        "apiVersion": "commands.dsh/v1alpha1", "kind": "Command", "name": "stats",
+        "spec": { "title": "Show session token and cache statistics",
+                  "placements": [{ "apiVersion": "tui.dsh/v1alpha1", "kind": "CommandLine" }] } },
+      { "id": "io.github.rayafriandion.dsh-oc-tui.new",
+        "apiVersion": "commands.dsh/v1alpha1", "kind": "Command", "name": "new",
+        "spec": { "title": "Start a new session",
+                  "placements": [{ "apiVersion": "tui.dsh/v1alpha1", "kind": "CommandLine" }] } },
+      { "id": "io.github.rayafriandion.dsh-oc-tui.resume",
+        "apiVersion": "commands.dsh/v1alpha1", "kind": "Command", "name": "resume",
+        "spec": { "title": "Resume a persisted session",
+                  "placements": [{ "apiVersion": "tui.dsh/v1alpha1", "kind": "CommandLine" }] } },
+      { "id": "io.github.rayafriandion.dsh-oc-tui.clear",
+        "apiVersion": "commands.dsh/v1alpha1", "kind": "Command", "name": "clear",
+        "spec": { "title": "Clear the transcript",
+                  "placements": [{ "apiVersion": "tui.dsh/v1alpha1", "kind": "CommandLine" }] } },
+      { "id": "io.github.rayafriandion.dsh-oc-tui.cancel",
+        "apiVersion": "commands.dsh/v1alpha1", "kind": "Command", "name": "cancel",
+        "spec": { "title": "Cancel the running turn",
+                  "placements": [{ "apiVersion": "tui.dsh/v1alpha1", "kind": "CommandLine" }] } },
+      { "id": "io.github.rayafriandion.dsh-oc-tui.rewind",
+        "apiVersion": "commands.dsh/v1alpha1", "kind": "Command", "name": "rewind",
+        "spec": { "title": "Rewind the session to an earlier point",
+                  "placements": [{ "apiVersion": "tui.dsh/v1alpha1", "kind": "CommandLine" }] } },
+      { "id": "io.github.rayafriandion.dsh-oc-tui.branch",
+        "apiVersion": "commands.dsh/v1alpha1", "kind": "Command", "name": "branch",
+        "spec": { "title": "Switch git branches on the empty page",
+                  "placements": [{ "apiVersion": "tui.dsh/v1alpha1", "kind": "CommandLine" }] } },
+      { "id": "io.github.rayafriandion.dsh-oc-tui.quit",
+        "apiVersion": "commands.dsh/v1alpha1", "kind": "Command", "name": "quit",
+        "spec": { "title": "Leave the TUI", "aliases": ["exit"],
+                  "placements": [{ "apiVersion": "tui.dsh/v1alpha1", "kind": "CommandLine" }] } }
+    ]
+  },
+  "overrides": [
+    { "target": "@deepseek-ai/dsh-base", "kind": "patch",
+      "description": "cordis.patch.yml inserts the tui-startup, tui-app, agent-presets and tool-ask-user rows." }
+  ]
+}

package/lib/boot-block.js

@@ -0,0 +1,129 @@
+// The page a boot refuses on.
+//
+// It is painted *instead of* the interface, never on top of it, because the
+// whole point is that nothing else may happen: no session, no settings, no
+// startup update check. The only input it accepts is quit.
+//
+// A card, not a toast: the failure is not something to dismiss and continue
+// past, and the information it carries (what is running, what was verified, what
+// to install) has to stay on screen while the reader copies a command out of it.
+import { Screen, makeStyle } from './term.js'
+import { displayWidth, truncateWidth, wrapText } from './util.js'
+import { t as tr } from './i18n.js'
+
+const PAD = 2
+const MAX_WIDTH = 78
+
+// Build the frame for the gate page. The caller owns the terminal, so this stays
+// a pure (cols, rows) -> Screen function with no knowledge of it.
+export function renderBootBlock(cols, rows, theme, info) {
+  return paintBootBlock(new Screen(cols, rows), theme, info)
+}
+
+/**
+ * Paint the version-gate page.
+ * @param {Screen} screen - the frame to paint into
+ * @param {object} theme - active colour theme
+ * @param {object} info - gate result: { verdict, version, range, recommended, tested, source }
+ */
+export function paintBootBlock(screen, theme, info) {
+  const background = makeStyle({ bg: theme.background })
+  screen.clear(background)
+
+  const width = Math.max(24, Math.min(screen.cols - PAD * 2, MAX_WIDTH))
+  const x0 = Math.max(1, Math.floor((screen.cols - width) / 2))
+  const inner = Math.max(12, width - PAD)
+
+  const title = tr(info.verdict === 'unsupported' ? 'boot.unsupportedTitle' : 'boot.unverifiedTitle')
+  const headline = { fg: theme.error, bold: true }
+  const label = { fg: theme.textMuted }
+  const value = { fg: theme.text }
+  const body = { fg: theme.textMuted }
+  const command = { fg: theme.primary, bold: true }
+  const hint = { fg: theme.textMuted, dim: true }
+
+  // The card is assembled from parts so a short terminal can drop the narration
+  // and keep the thing the page exists for: the command that fixes it. What is
+  // running and how to install the recommended version are essential; the
+  // alternatives go first, and each one only comes back if it still fits.
+  const rows = []
+  const blank = () => rows.push(null)
+  // A field wraps at the value column rather than truncating: the verified list is
+  // the one row that routinely outgrows the card, and cutting it with `…` hides
+  // versions the reader is being asked to choose between.
+  const field = (name, text, style = value) => {
+    const pad = displayWidth(name) < 12 ? ' '.repeat(12 - displayWidth(name)) : ' '
+    const width = Math.max(4, inner - 12)
+    const lines = wrapText(text, width)
+    rows.push([{ text: name + pad, style: label }, { text: lines[0] ?? '', style }])
+    for (const line of lines.slice(1)) rows.push([{ text: ' '.repeat(12), style: null }, { text: line, style }])
+  }
+  const wrap = (text, style = body) => {
+    for (const line of wrapText(text, inner)) rows.push([{ text: line, style }])
+  }
+  // Everything below pushes into `rows`; each splice cuts the block back out so
+  // the parts can be ordered and dropped independently of how they were written.
+  const cut = () => rows.splice(0)
+
+  rows.push([{ text: '⚠ ', style: headline }, { text: title, style: headline }])
+  blank()
+  field(tr('boot.runningLabel'), info.version ?? '—')
+  field(tr('boot.supportedLabel'), info.range === '' ? '—' : info.range)
+  if (info.recommended) field(tr('boot.recommendedLabel'), info.recommended, { fg: theme.success, bold: true })
+  if (info.tested?.length) field(tr('boot.verifiedLabel'), info.tested.join(' · '))
+  blank()
+  const head = cut()
+
+  wrap(tr(info.verdict === 'unsupported' ? 'boot.unsupportedBody' : 'boot.unverifiedBody', {
+    version: info.version ?? '?',
+    range: info.range,
+    recommended: info.recommended ?? '',
+    verified: (info.tested ?? []).join(' · '),
+  }))
+  blank()
+  const explanation = cut()
+
+  wrap(tr('boot.installHint'))
+  const installHint = cut()
+
+  rows.push([{ text: '    npm i -g @deepseek-ai/dsh@' + (info.recommended ?? ''), style: command }])
+  blank()
+  const installCommand = cut()
+
+  wrap(tr('boot.updatePluginHint'))
+  rows.push([{ text: '    npm i -g dsh-oc-tui@latest', style: command }])
+  const alternative = cut()
+
+  // The bottom row is the footer, so the card is centred in the rows above it.
+  // Reading order is fixed by this list; membership is what the budget decides.
+  const footerRow = Math.max(0, screen.rows - 1)
+  const budget = footerRow
+  const kept = new Set([head, installCommand])
+  const card = () => [head, explanation, installHint, installCommand, alternative]
+    .flatMap((part) => (kept.has(part) ? part : []))
+  // Added by importance, so a window that only fits one of them keeps the
+  // sentence that introduces the command rather than the alternative route.
+  for (const part of [installHint, explanation, alternative]) {
+    if (card().length + part.length > budget) continue
+    kept.add(part)
+  }
+
+  const lines = card()
+  const top = Math.max(0, Math.floor((budget - lines.length) / 2))
+  const limit = Math.max(0, Math.min(lines.length, budget - top))
+  for (let i = 0; i < limit; i++) {
+    const row = lines[i]
+    if (!row) continue
+    let x = x0
+    for (const segment of row) {
+      x = screen.text(x, top + i, segment.text, makeStyle({ ...segment.style, bg: theme.background }))
+    }
+  }
+  // The one line that must survive any window height: how to get out. It is a
+  // footer, not a card row, so a tall card being truncated cannot swallow it —
+  // and it clears its row first, because a card that ran into it would otherwise
+  // leave its own text trailing after the hint.
+  screen.fill(0, footerRow, screen.cols, ' ', background)
+  screen.text(x0, footerRow, truncateWidth(tr('boot.exitHint'), inner), makeStyle({ ...hint, bg: theme.background }))
+  return screen
+}

package/lib/diagnostics.js

@@ -1,120 +1,162 @@
-// Host diagnostics captured while the TUI owns the alternate screen.
-//
-// Plugins in this process report through `console.warn` / `console.error` when
-// no logger exporter is mounted — the LLM adapters do exactly that for model
-// listing problems. On an ordinary CLI that is fine; here every one of those
-// writes lands on the alt screen the renderer believes it owns, leaving
-// unpainted text behind that the diffing painter never corrects.
-//
-// So the process streams are diverted for as long as the alt screen is up. The
-// text is appended to a log file the user can be pointed at, and replayed to the
-// real stderr on restore, after the alt screen is gone and it can do no harm.
-import fs from 'node:fs'
-import path from 'node:path'
-
-// Beyond this the in-memory copy stops growing: a plugin stuck in a warn loop
-// must not be able to exhaust the heap. The file keeps the full text either way.
-const MAX_KEPT_BYTES = 256 * 1024
-// The log is truncated once it passes this. A plugin that warns on every frame
-// would otherwise grow the file without bound across a long session.
-const MAX_LOG_BYTES = 1024 * 1024
-
-function streamText(chunk, encoding) {
-  if (Buffer.isBuffer(chunk)) return chunk.toString('utf8')
-  return typeof chunk === 'string' ? chunk : String(chunk)
-}
-
-// Intercept both process streams. Returns a handle with the captured text, a
-// live count, and `restore()`.
-//
-// `onFirst` fires exactly once, on the first diverted write: the caller uses it
-// for a single toast rather than one per line. It is called after the write has
-// been recorded, never from inside a console method, so a listener that itself
-// logs cannot recurse into the capture.
-export function captureDiagnostics({ logPath, onFirst } = {}) {
-  const streams = [
-    { stream: process.stdout, name: 'stdout' },
-    { stream: process.stderr, name: 'stderr' },
-  ]
-  const undo = []
-  const state = {
-    count: 0,
-    bytes: 0,
-    kept: [],
-    truncated: false,
-    restored: false,
-  }
-
-  // Size is read once and then tracked, so a quiet session with no host output
-  // never touches the filesystem at all.
-  let logBytes = null
-
-  const record = (name, text) => {
-    if (!text) return
-    state.count++
-    // Stamping each write rather than each line keeps multi-line stack traces
-    // attached to the moment they happened without parsing them here.
-    const entry = `[${new Date().toISOString()}] [${name}] ${text}`
-    if (logPath) {
-      const line = entry.endsWith('\n') ? entry : entry + '\n'
-      try {
-        fs.mkdirSync(path.dirname(logPath), { recursive: true })
-        if (logBytes === null) {
-          try { logBytes = fs.statSync(logPath).size } catch { logBytes = 0 }
-        }
-        // Rotate by truncation: this file exists to answer "what did the host
-        // complain about just now", so the newest lines are the ones worth
-        // keeping.
-        if (logBytes > MAX_LOG_BYTES) {
-          fs.writeFileSync(logPath, '')
-          logBytes = 0
-        }
-        fs.appendFileSync(logPath, line)
-        logBytes += Buffer.byteLength(line)
-      } catch {
-        // A read-only home directory must not take the TUI down with it; the
-        // in-memory copy below still carries the text to restore().
-      }
-    }
-    if (state.bytes < MAX_KEPT_BYTES) {
-      state.kept.push(text)
-      state.bytes += Buffer.byteLength(text)
-    } else {
-      state.truncated = true
-    }
-    if (state.count === 1 && typeof onFirst === 'function') {
-      try { onFirst() } catch { /* a listener must not break the capture */ }
-    }
-  }
-
-  for (const { stream, name } of streams) {
-    const original = stream.write
-    if (typeof original !== 'function') continue
-    stream.write = function (chunk, encoding, callback) {
-      // Diverted writes report success and still fire the callback: a writer
-      // that waits for it would otherwise hang the host mid-turn.
-      record(name, streamText(chunk, encoding))
-      if (typeof encoding === 'function') encoding()
-      else if (typeof callback === 'function') callback()
-      return true
-    }
-    undo.push(() => { stream.write = original })
-  }
-
-  return {
-    get count() { return state.count },
-    get truncated() { return state.truncated },
-    // Everything captured, in write order, for the post-exit replay.
-    text() { return state.kept.join('') },
-    restore() {
-      if (state.restored) return
-      state.restored = true
-      for (let i = undo.length - 1; i >= 0; i--) undo[i]()
-      // Replay through the real streams, now that they no longer paint over the
-      // alt screen. Nothing here goes through record().
-      if (state.kept.length > 0) {
-        try { process.stderr.write(state.kept.join('')) } catch { /* closed on shutdown */ }
-      }
-    },
-  }
-}
+// Host diagnostics captured while the TUI owns the alternate screen.
+//
+// Plugins in this process report through `console.warn` / `console.error` when
+// no logger exporter is mounted — the LLM adapters do exactly that for model
+// listing problems. On an ordinary CLI that is fine; here every one of those
+// writes lands on the alt screen the renderer believes it owns, leaving
+// unpainted text behind that the diffing painter never corrects.
+//
+// So the process streams are diverted for as long as the alt screen is up. The
+// text is appended to a log file the user can be pointed at, and replayed to the
+// real stderr on restore, after the alt screen is gone and it can do no harm.
+import fs from 'node:fs'
+import path from 'node:path'
+
+// Beyond this the in-memory copy stops growing: a plugin stuck in a warn loop
+// must not be able to exhaust the heap. The file keeps the full text either way.
+const MAX_KEPT_BYTES = 256 * 1024
+// The log is truncated once it passes this. A plugin that warns on every frame
+// would otherwise grow the file without bound across a long session.
+const MAX_LOG_BYTES = 1024 * 1024
+
+function streamText(chunk, encoding) {
+  if (Buffer.isBuffer(chunk)) return chunk.toString('utf8')
+  return typeof chunk === 'string' ? chunk : String(chunk)
+}
+
+// Intercept both process streams. Returns a handle with the captured text, a
+// live count, and `restore()`.
+//
+// `onFirst` fires exactly once, on the first diverted write: the caller uses it
+// for a single toast rather than one per line. It is called after the write has
+// been recorded, never from inside a console method, so a listener that itself
+// logs cannot recurse into the capture.
+export function captureDiagnostics({ logPath, onFirst } = {}) {
+  const streams = [
+    { stream: process.stdout, name: 'stdout' },
+    { stream: process.stderr, name: 'stderr' },
+  ]
+  const undo = []
+  const state = {
+    count: 0,
+    bytes: 0,
+    kept: [],
+    truncated: false,
+    restored: false,
+  }
+
+  // Size is read once and then tracked, so a quiet session with no host output
+  // never touches the filesystem at all.
+  let logBytes = null
+  let directoryReady = false
+  // The log is written in batches, not once per diverted write. `record` runs
+  // inside the host's own write path, and an MCP server started through `npx`
+  // prints its download progress there in hundreds of small chunks: a
+  // synchronous append, a stat and a mkdir per chunk blocked the frame loop long
+  // enough to read as a stutter — worst of all while MCP servers were loading,
+  // which is exactly when that output arrives. The in-memory copy stays exact
+  // and immediate; only the file lags by one flush interval.
+  const FLUSH_MS = 250
+  const FLUSH_BYTES = 64 * 1024
+  let pending = ''
+  let flushTimer = null
+
+  const flush = () => {
+    if (flushTimer) {
+      clearTimeout(flushTimer)
+      flushTimer = null
+    }
+    if (!logPath || pending === '') return
+    const text = pending
+    pending = ''
+    try {
+      if (!directoryReady) {
+        fs.mkdirSync(path.dirname(logPath), { recursive: true })
+        directoryReady = true
+      }
+      if (logBytes === null) {
+        try { logBytes = fs.statSync(logPath).size } catch { logBytes = 0 }
+      }
+      // Rotate by truncation: this file exists to answer "what did the host
+      // complain about just now", so the newest lines are the ones worth
+      // keeping.
+      if (logBytes + Buffer.byteLength(text) > MAX_LOG_BYTES) {
+        fs.writeFileSync(logPath, '')
+        logBytes = 0
+      }
+      fs.appendFileSync(logPath, text)
+      logBytes += Buffer.byteLength(text)
+    } catch {
+      // A read-only home directory must not take the TUI down with it; the
+      // in-memory copy below still carries the text to restore().
+    }
+  }
+
+  const queueForLog = (line) => {
+    pending += line
+    if (Buffer.byteLength(pending) >= FLUSH_BYTES) {
+      flush()
+      return
+    }
+    if (flushTimer) return
+    flushTimer = setTimeout(flush, FLUSH_MS)
+    // The timer must never be the reason the process stays alive.
+    if (typeof flushTimer.unref === 'function') flushTimer.unref()
+  }
+
+  const record = (name, text) => {
+    if (!text) return
+    state.count++
+    // Stamping each write rather than each line keeps multi-line stack traces
+    // attached to the moment they happened without parsing them here.
+    const entry = `[${new Date().toISOString()}] [${name}] ${text}`
+    if (logPath) queueForLog(entry.endsWith('\n') ? entry : entry + '\n')
+    if (state.bytes < MAX_KEPT_BYTES) {
+      state.kept.push(text)
+      state.bytes += Buffer.byteLength(text)
+    } else {
+      state.truncated = true
+    }
+    if (state.count === 1 && typeof onFirst === 'function') {
+      try { onFirst() } catch { /* a listener must not break the capture */ }
+    }
+  }
+
+  for (const { stream, name } of streams) {
+    const original = stream.write
+    if (typeof original !== 'function') continue
+    stream.write = function (chunk, encoding, callback) {
+      // Diverted writes report success and still fire the callback: a writer
+      // that waits for it would otherwise hang the host mid-turn.
+      record(name, streamText(chunk, encoding))
+      if (typeof encoding === 'function') encoding()
+      else if (typeof callback === 'function') callback()
+      return true
+    }
+    undo.push(() => { stream.write = original })
+  }
+
+  return {
+    get count() { return state.count },
+    get truncated() { return state.truncated },
+    // Everything captured, in write order, for the post-exit replay.
+    text() { return state.kept.join('') },
+    // Write the log out now instead of on the next flush tick. A caller that
+    // is about to read the file — the tests, a user asked to look at it —
+    // needs the tail to be on disk already.
+    flush,
+    restore() {
+      if (state.restored) return
+      state.restored = true
+      // Pending log text would otherwise be lost on the way out, which is
+      // exactly the tail a user is asked to look at when something failed.
+      flush()
+      for (let i = undo.length - 1; i >= 0; i--) undo[i]()
+      // Replay through the real streams, now that they no longer paint over the
+      // alt screen. Nothing here goes through record().
+      if (state.kept.length > 0) {
+        try { process.stderr.write(state.kept.join('')) } catch { /* closed on shutdown */ }
+      }
+    },
+  }
+}