agent-dag 3.22.0 → 3.22.3

package/src/server/term.mjs

@@ -1,686 +0,0 @@
-// Everything the deck knows about the terminal it is printing into.
-//
-// The terminal is the first surface of this product and, for the seconds before
-// the browser opens, the only one — so it gets the same treatment the canvas
-// got. The rules below are the whole of it: detect what this terminal can do,
-// then degrade, rather than picking the floor and printing the same 16 colours
-// into a pipe, a CI log and a truecolor emulator alike.
-//
-// It lives here, apart from bin/deck.js, for the reason supervisor.mjs and
-// npx.mjs do: bin/deck.js installs hooks and binds a port the moment it is
-// imported, so none of this could be checked any other way — and "what does the
-// output look like at 40 columns, with NO_COLOR, on a Windows console" is
-// exactly the kind of question that is only ever answered by asserting it.
-//
-// Nothing here writes anything or reads process state on its own: every input
-// (env, isTTY, platform, columns) is a parameter, defaulted from the real thing.
-// The two exceptions are the cursor constants, which are strings the caller
-// writes, because who restores the cursor and when is a lifecycle question and
-// belongs with the lifecycle.
-
-// ── colour profile ───────────────────────────────────────────────────────────
-//
-// Detected once, in the order the conventions themselves establish:
-// NO_COLOR (no-color.org — present and non-empty means no colour, whatever the
-// value) beats FORCE_COLOR beats what the terminal advertises. Truecolor is
-// effectively universal now, and it is the only tier on which the deck's accent
-// is actually the deck's accent rather than whatever the user's theme decided
-// cyan is — so it is worth asking for, and worth degrading from cleanly.
-
-/** Present and non-empty, which is what every one of these variables means. */
-const set = (v) => v != null && v !== "";
-
-/** Anything below a space, or DEL. A URL is going inside an escape sequence, so
- *  a control character in it would close that sequence early. */
-const hasControl = (s) => [...String(s)].some((c) => c.charCodeAt(0) <= 0x20 || c.charCodeAt(0) === 0x7f);
-
-/** Terminals that do truecolor without saying so in COLORTERM. */
-const TRUECOLOR_PROGRAMS = new Set(["iTerm.app", "vscode", "WezTerm", "ghostty", "Hyper", "rio", "Tabby"]);
-
-/** FORCE_COLOR's levels, as every CLI that honours it reads them. `undefined`
- *  means the variable is absent and detection continues. */
-function forcedProfile(raw) {
-  if (raw == null) return undefined;
-  const v = String(raw).trim().toLowerCase();
-  if (v === "0" || v === "false") return "none";
-  if (v === "2") return "ansi256";
-  if (v === "3") return "truecolor";
-  return "ansi16"; // "", "1", "true", anything else: colour, at the safe floor
-}
-
-/**
- * What this terminal can be asked for: "none" | "ansi16" | "ansi256" | "truecolor".
- *
- * A Windows TTY floors at ansi16 rather than none: libuv translates SGR into
- * console API calls for consoles that cannot parse escapes themselves, so the
- * 16 colours arrive on legacy conhost too. Nothing above that tier is assumed
- * there — Windows Terminal says so through WT_SESSION, and conhost never does.
- */
-export function colorProfile({ env = process.env, isTTY = false, platform = process.platform } = {}) {
-  if (set(env.NO_COLOR)) return "none";
-  const forced = forcedProfile(env.FORCE_COLOR);
-  if (forced !== undefined) return forced;
-  if (!isTTY) return "none";
-
-  const term = String(env.TERM ?? "").toLowerCase();
-  if (term === "dumb") return "none";
-
-  const colorterm = String(env.COLORTERM ?? "").toLowerCase();
-  if (colorterm === "truecolor" || colorterm === "24bit") return "truecolor";
-  if (set(env.WT_SESSION)) return "truecolor";
-  if (TRUECOLOR_PROGRAMS.has(String(env.TERM_PROGRAM ?? ""))) return "truecolor";
-  if (term === "xterm-kitty" || term === "alacritty" || term.includes("truecolor")) return "truecolor";
-  if (term.includes("256")) return "ansi256";
-  // A TTY that advertises nothing still takes colour on every platform we
-  // support; 16 is the tier nothing has to advertise to have.
-  return "ansi16";
-}
-
-// ── colours ──────────────────────────────────────────────────────────────────
-
-/** rgb → the nearest xterm-256 index: the 6×6×6 cube, or the 24-step grey ramp
- *  for anything neutral, which is where the muted tones land. */
-function to256(r, g, b) {
-  if (r === g && g === b) {
-    if (r < 8) return 16;
-    if (r > 248) return 231;
-    return Math.round(((r - 8) / 247) * 24) + 232;
-  }
-  return 16 + 36 * Math.round((r / 255) * 5) + 6 * Math.round((g / 255) * 5) + Math.round((b / 255) * 5);
-}
-
-/**
- * One colour, expressed as far as this profile reaches.
- *
- * `fallback` is the 16-colour SGR to use when that is all there is — chosen per
- * colour rather than derived, because the nearest of eight hues to a pastel is
- * a question with a taste answer, not an arithmetic one.
- */
-export function fg([r, g, b], profile, fallback) {
-  if (profile === "truecolor") return `\x1b[38;2;${r};${g};${b}m`;
-  if (profile === "ansi256") return `\x1b[38;5;${to256(r, g, b)}m`;
-  if (profile === "ansi16") return fallback;
-  return "";
-}
-
-// The canvas' own tokens (src/web/styles.css), so the terminal and the page are
-// one product rather than two. The ramp is the wordmark's vertical gradient:
-// lit at the top, settling into the deeper tone at the baseline.
-const BRAND = {
-  accentSoft: [[186, 230, 253], "\x1b[96m"],
-  accent:     [[125, 211, 252], "\x1b[96m"],
-  accentDeep: [[56, 189, 248],  "\x1b[36m"],
-  ok:         [[134, 239, 172], "\x1b[32m"],
-  warn:       [[252, 211, 77],  "\x1b[33m"],
-  err:        [[252, 165, 165], "\x1b[31m"],
-  muted:      [[126, 130, 140], "\x1b[2m"],
-};
-
-/**
- * The semantic names every call site uses — no raw escape ever appears in
- * bin/deck.js again. Empty strings under "none", so the same template literals
- * produce escape-free output in a pipe without a branch at each one.
- */
-export function palette(profile) {
-  const on = profile !== "none";
-  const out = {
-    reset: on ? "\x1b[0m" : "",
-    bold: on ? "\x1b[1m" : "",
-    dim: on ? "\x1b[2m" : "",
-  };
-  for (const [name, [rgb, fallback]] of Object.entries(BRAND)) out[name] = fg(rgb, profile, fallback);
-  return out;
-}
-
-// ── hyperlinks ───────────────────────────────────────────────────────────────
-//
-// OSC 8 is an allowlist rather than a probe: a terminal that does not know the
-// sequence is supposed to ignore it, and most do, but "most" is not a promise
-// worth making to a legacy Windows console — and tmux below 3.4 passes the
-// escape through mangled, which is worse than plain text. So links are emitted
-// only where they are known to arrive.
-
-const HYPERLINK_PROGRAMS = new Set(["iTerm.app", "vscode", "WezTerm", "ghostty", "Hyper", "rio", "Tabby"]);
-
-export function supportsHyperlinks({ env = process.env, profile = "truecolor" } = {}) {
-  // NO_COLOR takes hyperlinks with it: the convention is about decoration, and
-  // an escape sequence wrapped around a path is decoration.
-  if (profile === "none") return false;
-  const term = String(env.TERM ?? "").toLowerCase();
-  if (set(env.TMUX) || term.startsWith("screen")) return false;
-  if (HYPERLINK_PROGRAMS.has(String(env.TERM_PROGRAM ?? ""))) return true;
-  if (set(env.WT_SESSION)) return true;
-  if (set(env.KITTY_WINDOW_ID) || term === "xterm-kitty") return true;
-  if (set(env.KONSOLE_VERSION) || set(env.DOMTERM)) return true;
-  const vte = Number.parseInt(String(env.VTE_VERSION ?? ""), 10);
-  return Number.isFinite(vte) && vte >= 5000; // GNOME Terminal 3.26+
-}
-
-/** `text` as a link to `url`, or just `text`. BEL-terminated, which is the form
- *  the widest set of terminals accepts. A url carrying a control character is
- *  dropped rather than escaped — it could only have come from a path we should
- *  not be linking anyway. */
-export function link(text, url, enabled) {
-  if (!enabled || !url || hasControl(url)) return text;
-  return `\x1b]8;;${url}\x07${text}\x1b]8;;\x07`;
-}
-
-// ── glyphs ───────────────────────────────────────────────────────────────────
-//
-// Windows Terminal renders all of these; `cmd.exe` on a non-UTF-8 code page
-// renders none of them, and this project's rule is that everything works on
-// Windows. So there are two tiers and every glyph the deck prints — punctuation
-// included, since an em dash is as absent from CP437 as a check mark — comes
-// from one of them.
-
-const UNICODE_GLYPHS = {
-  ok: "✓", fail: "✗", warn: "⚠", stop: "◉", restart: "↻", cancel: "✕",
-  up: "↑", play: "▶", pulse: "●",
-  arrow: "→", ellipsis: "…", dash: "—", bullet: "·",
-};
-
-const ASCII_GLYPHS = {
-  ok: "+", fail: "x", warn: "!", stop: "*", restart: "~", cancel: "x",
-  up: "^", play: ">", pulse: "*",
-  arrow: "->", ellipsis: "...", dash: "-", bullet: "-",
-};
-
-/**
- * Whether this terminal can be trusted with the box-drawing and arrow glyphs.
- *
- * Everywhere but Windows, yes — except the Linux virtual console, whose font is
- * 256 glyphs and none of them are these. On Windows it is the other way round:
- * an allowlist of the emulators that ship a real font and a UTF-8 code page,
- * because the default console does neither.
- */
-export function unicodeOK({ env = process.env, platform = process.platform } = {}) {
-  const term = String(env.TERM ?? "").toLowerCase();
-  if (platform !== "win32") return term !== "linux" && term !== "dumb";
-  if (set(env.WT_SESSION)) return true;
-  if (String(env.TERM_PROGRAM ?? "") === "vscode") return true;
-  if (set(env.ConEmuTask) || set(env.WSL_DISTRO_NAME)) return true;
-  if (String(env.TERMINAL_EMULATOR ?? "") === "JetBrains-JediTerm") return true;
-  return term.startsWith("xterm") || term === "alacritty";
-}
-
-export function glyphs(unicode) {
-  return unicode ? { ...UNICODE_GLYPHS } : { ...ASCII_GLYPHS };
-}
-
-// One definition, for the banner, the step spinner and anything later. The
-// braille frames are the nicest thing a terminal can do with one cell; the
-// ASCII tier gets the rotating bar, which is the only spinner CP437 has.
-const BRAILLE_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
-const ASCII_FRAMES = ["|", "/", "-", "\\"];
-
-export function spinnerFrames(unicode) {
-  return unicode ? BRAILLE_FRAMES.slice() : ASCII_FRAMES.slice();
-}
-
-/** When a spinner starts saying how long it has been going.
- *
- *  #742: a spinner four seconds in looks exactly like one four hundred
- *  milliseconds in, and that is the whole of "is this thing stuck". A number
- *  answers it. Three seconds, because under that the number would be on screen
- *  for a blink on every ordinary boot and would be noise rather than an answer
- *  — nobody doubts a step that has not yet lasted as long as it takes to doubt
- *  one. */
-export const SPINNER_ELAPSED_AFTER_MS = 3_000;
-
-/**
- * The seconds a spinner shows beside its label, or "" while it is too young to
- * have anything worth saying.
- *
- * Whole seconds, floored, and never a tenth: a number that changes ten times a
- * second is a second spinner rather than an answer about the first one. Here
- * rather than in bin/deck.js because that file runs a deck when it is imported,
- * and this is the one part of `step` worth holding still in a test.
- */
-export function elapsedSuffix(ms, after = SPINNER_ELAPSED_AFTER_MS) {
-  return ms < after ? "" : `  ${Math.floor(ms / 1000)}s`;
-}
-
-/**
- * How long a deck has been up, in the two units that matter and no more.
- *
- * `--status` and `--stop` both print this, and the question behind it is always
- * "is this the deck I started, or one I forgot about" — which "3h 12m" answers
- * and "11543s" does not. Two units, because the second one stops being
- * interesting as soon as the first is large: nobody reading "2d" wants the
- * minutes.
- *
- * Seconds under a minute, because that is the unit a deck started moments ago
- * is measured in and "up just now" is not an answer to "how long". A clock that
- * went backwards, or a `startedAt` from a machine whose time has since been
- * corrected, reads as `0s` rather than as a negative duration.
- */
-export function sinceLabel(ms) {
-  const s = Math.floor(Number(ms) / 1000);
-  if (!Number.isFinite(s) || s < 0) return "0s";
-  if (s < 60) return `${s}s`;
-  const m = Math.floor(s / 60);
-  if (m < 60) return `${m}m`;
-  const h = Math.floor(m / 60);
-  if (h < 24) return h > 0 && m % 60 > 0 ? `${h}h ${m % 60}m` : `${h}h`;
-  const d = Math.floor(h / 24);
-  return h % 24 > 0 ? `${d}d ${h % 24}h` : `${d}d`;
-}
-
-// ── motion ───────────────────────────────────────────────────────────────────
-
-/**
- * Whether anything is allowed to move — the terminal's `prefers-reduced-motion`.
- *
- * A pipe, a file, a CI log and a NO_COLOR terminal all get the same treatment:
- * no sleeps, no `\r` repaints, no spinner, no pulse. Every one of those either
- * cannot show motion or is somebody's log file, and a log file full of carriage
- * returns is the artefact this rule exists to prevent.
- */
-export function motionOK({ env = process.env, isTTY = false, profile = colorProfile({ env, isTTY }) } = {}) {
-  if (!isTTY || profile === "none") return false;
-  const ci = String(env.CI ?? "").trim().toLowerCase();
-  if (set(ci) && ci !== "0" && ci !== "false") return false;
-  return true;
-}
-
-// ── width ────────────────────────────────────────────────────────────────────
-
-/** The visible text: SGR colour and OSC 8 hyperlinks removed. Everything that
- *  measures a line for layout measures it through here — a padded line that
- *  counted its own escapes is how a `\r` repaint starts leaving debris. */
-export function stripAnsi(s) {
-  return String(s)
-    .replace(/\x1b\]8;;.*?(?:\x07|\x1b\\)/g, "")
-    .replace(/\x1b\[[0-9;?]*[a-zA-Z]/g, "");
-}
-
-export function visibleWidth(s) {
-  return stripAnsi(s).length;
-}
-
-/** How wide the terminal is, or 80 when it will not say — a pipe, a CI runner,
- *  a terminal that never sent SIGWINCH. 80 is the assumption every one of them
- *  is already built around, and the layout below never needs more than 40. */
-export function termColumns(stream = process.stdout, env = process.env) {
-  const c = stream?.columns;
-  if (Number.isInteger(c) && c > 0) return c;
-  // COLUMNS, the POSIX spelling of this question, and the only answer a DETACHED
-  // deck has. Its stdout is the log file, so the stream knows nothing about a
-  // width — but the launcher is watching that file from a real terminal and
-  // passes its own width down, so the boot report is laid out for the terminal
-  // a person is actually reading it in rather than for the 80 below.
-  const n = Number.parseInt(String(env?.COLUMNS ?? "").trim(), 10);
-  return Number.isInteger(n) && n > 0 ? n : 80;
-}
-
-/** The status column, computed from the labels rather than counted into each
- *  string by hand. A label one character longer used to break the alignment of
- *  every row silently. */
-export function labelColumn(labels) {
-  return labels.reduce((w, l) => Math.max(w, String(l).length), 0);
-}
-
-/**
- * `s` trimmed to `max` columns, from whichever end matters least.
- *
- * A path, a URL or a version has no spaces in it and is identified by its tail
- * — `…/agent-dag/hook.js` still says which file — so the head goes. A sentence
- * is identified by its head, and `…nel enabled)` says nothing at all, so its
- * tail goes instead. Below the width where the ellipsis plus a few characters
- * would still mean something, the detail is dropped rather than reduced to
- * punctuation; the label beside it already says which row this is.
- */
-export function fit(s, max, ellipsis = "…") {
-  const text = String(s);
-  if (text.length <= max) return text;
-  if (max < ellipsis.length + 3) return "";
-  const room = max - ellipsis.length;
-  return /\s/.test(text) ? text.slice(0, room) + ellipsis : ellipsis + text.slice(text.length - room);
-}
-
-/**
- * A failure, reduced to the one line it is safe to print while the deck is
- * painting.
- *
- * Everything bin/deck.js writes after the banner is a `\r`-rewritten row — the
- * spinner in `step`, the pulse line, which repaints every 800ms — so a write
- * that arrives from an async callback lands in the middle of one of them. A
- * single short line is survivable: it ends in a newline, the next repaint
- * starts on a fresh row, and the report above it is still on screen. A
- * subprocess's stack trace is not: fifteen lines scroll the entire startup
- * report away and leave the pulse mid-frame. Reported from Windows (#432),
- * where a broken npm shim put two Node stack traces over the boot output.
- *
- * Three things happen here, and the order matters.
- *
- * The most informative line is chosen rather than the first one, because the
- * first line of a Node stack trace is `node:internal/modules/cjs/loader:1573`
- * and the line that names the actual failure — `Error: Cannot find module …` —
- * is five lines below it.
- *
- * Every control character is replaced, not just the newlines. A lone `\r` is a
- * cursor jump to column 0, so a CRLF stack trace that only had its `\n`
- * removed would still overwrite whatever the deck had drawn on that row — and
- * CRLF is what a Windows child writes, which is the platform this exists for.
- * An ESC would open an escape sequence out of a string the deck did not write.
- *
- * And the result is fitted to the room the caller has left, so the one line
- * stays one line: a message that wraps is two rows, and the `\r` that follows
- * only ever reaches the second of them. The ellipsis defaults to the ASCII one
- * rather than `…`, because callers of this are error paths in modules that
- * know nothing about the terminal's glyph tier — and a `…` on a cmd.exe code
- * page is a question mark in the middle of the only clue the user got.
- *
- * @param room how many columns are free after whatever prefix the caller prints.
- */
-export function oneLine(text, room = 80, ellipsis = "...") {
-  const lines = stripAnsi(String(text ?? ""))
-    .split("\n")
-    // eslint-disable-next-line no-control-regex
-    .map((l) => l.replace(/[\x00-\x1f\x7f]/g, " ").trim())
-    .filter(Boolean);
-  if (!lines.length) return "";
-  // "Error:", "TypeError:", "Error [ERR_MODULE_NOT_FOUND]:" — the line a reader
-  // would have picked out of the dump themselves. The optional prefix is what
-  // makes a bare "Error:" match as well as a named subclass.
-  const named = lines.find((l) => /^[\w$]*Error\b/.test(l));
-  return fit(named ?? lines[0], Math.max(8, room), ellipsis);
-}
-
-const same = (s) => s;
-
-/**
- * One aligned status row: `  ✓  label            detail`.
- *
- * Laid out on the plain text and painted afterwards, so colour and hyperlinks
- * never enter the arithmetic. The last cell of the line is left empty: a
- * terminal that fills its final column either wraps or leaves the cursor in a
- * place the next `\r` cannot recover from.
- *
- * `keep` is for the one detail nobody can act on a fragment of — the URL. When
- * it will not fit beside its label it moves to its own line under the gutter
- * rather than losing its port to an ellipsis; a truncated address is not a
- * shorter address, it is no address. The result then contains a newline, which
- * is why callers write it whole.
- */
-export function statusLine({
-  mark = " ", label = "", detail = "", labelWidth = 0, columns = 80, indent = 2, paint = {},
-  ellipsis = "…", keep = false,
-} = {}) {
-  // A blank gutter is painted by nobody: colouring a space costs two escapes
-  // and shows nothing, and rows with no mark are the majority of the quiet ones.
-  const paintMark = stripAnsi(mark).trim() ? (paint.mark ?? same) : same;
-  const paintLabel = paint.label ?? same;
-  const paintDetail = paint.detail ?? same;
-  const pad = " ".repeat(indent);
-  const head = `${pad}${paintMark(mark)}  ${paintLabel(label)}`;
-
-  if (!detail) return head;
-
-  const padded = label.padEnd(Math.max(labelWidth, label.length));
-  const used = indent + stripAnsi(mark).length + 2 + padded.length + 2;
-  const room = columns - used - 1;
-  const plain = stripAnsi(detail);
-  if (keep && plain.length > room) {
-    // Under the gutter if that still fits, then flush left, then wrapped —
-    // there is nothing else to try when the address is wider than the terminal.
-    const under = [indent + 3, indent, 0].find(n => n + plain.length < columns) ?? 0;
-    return `${head}\n${" ".repeat(under)}${paintDetail(detail)}`;
-  }
-  const fitted = plain.length <= room ? detail : fit(plain, room, ellipsis);
-  if (!fitted) return head;
-  return `${pad}${paintMark(mark)}  ${paintLabel(padded)}  ${paintDetail(fitted)}`;
-}
-
-// ── wordmark ─────────────────────────────────────────────────────────────────
-//
-// Drawn, not pasted out of a figlet font — six letters on a 4×6 pixel grid,
-// printed two pixel rows to a text row with the half-block characters, which is
-// what gives it a lowercase with real ascenders in three lines instead of six.
-// The old banner said `agents-deck`, a name the repo, the command, the README
-// and the docs stopped using; this one says what the product is called.
-
-const LETTERS = {
-  c: ["....", "....", ".###", "#...", "#...", ".###"],
-  d: ["...#", "...#", ".###", "#..#", "#..#", ".###"],
-  e: ["....", "....", ".###", "####", "#...", ".###"],
-  k: ["#...", "#...", "#.##", "##..", "#.#.", "#..#"],
-};
-
-/** Two pixel rows into one text row: ▀ upper only, ▄ lower only, █ both. */
-function squash(top, bottom) {
-  let out = "";
-  for (let i = 0; i < top.length; i++) {
-    const t = top[i] === "#";
-    const b = bottom[i] === "#";
-    out += t && b ? "█" : t ? "▀" : b ? "▄" : " ";
-  }
-  return out;
-}
-
-function renderWord(word) {
-  const rows = ["", "", ""];
-  for (const [n, ch] of [...word].entries()) {
-    const px = LETTERS[ch];
-    for (let r = 0; r < 3; r++) rows[r] += (n ? " " : "") + squash(px[r * 2], px[r * 2 + 1]);
-  }
-  return rows.map((r) => r.replace(/\s+$/, ""));
-}
-
-/** The drawn mark itself, three text rows of half-blocks.
- *
- *  Exported for one reader, and it is a test rather than a caller (#383). This
- *  is the ONLY place the art's true width can be measured: `renderWord` trims
- *  each row's trailing blanks, so the rows are not all the same length, and the
- *  arithmetic in WORDMARK_WIDTH below is a hand-computed prediction of the
- *  widest of them. Nothing in the banner path compares the two — `wordmark()`
- *  gates on WORDMARK_WIDTH and then prints THESE lines — so an under-counting
- *  width lets the art render into a terminal too narrow to hold it and the
- *  three rows wrap into six. See wordmark-art-width.test.ts, which is the
- *  comparison this export exists to make possible. */
-export const WORDMARK_LINES = renderWord("ccdeck");
-/** 29 columns of art, plus the two-space indent every other line uses. */
-export const WORDMARK_WIDTH = 2 + LETTERS.c[0].length * 6 + 5;
-
-/**
- * The tagline, longest version that fits — the name and version are the part
- * that must survive, the rest is context.
- *
- * `prefix` is how many columns are already spent on the line the tagline lands
- * on, and it is a parameter because the three layouts below do not agree on it
- * (#383). In the full banner the tagline gets a line of its own behind a
- * two-space indent; in the compact and plain ones it shares the line with the
- * product name, which costs eight or nine columns more. This budget was
- * hard-coded at 2 for all three, so between 21 and 31 columns — the widths where
- * the compact form is chosen and the medium tagline still looks affordable —
- * the banner printed a 36-column line into a terminal that could not hold it and
- * the first thing a user saw wrapped. `columns - 1` keeps the last cell empty,
- * because a line ending exactly at the right margin makes some terminals wrap
- * anyway.
- */
-function tagline(version, columns, bullet, prefix) {
-  const v = `v${version}`;
-  const options = [
-    `${v} ${bullet} live agent DAG ${bullet} Claude Code + Codex`,
-    `${v} ${bullet} live agent DAG`,
-    v,
-  ];
-  return options.find((o) => o.length + prefix <= columns - 1) ?? v;
-}
-
-// What each layout spends before the tagline starts, counted off the strings
-// built in `wordmark` below: "  ccdeck " for plain, "  ccdeck  " for compact,
-// and the bare two-space indent for the full banner's own tagline line.
-const PLAIN_PREFIX_W   = "  ccdeck ".length;
-const COMPACT_PREFIX_W = "  ccdeck  ".length;
-const TAG_INDENT_W     = "  ".length;
-
-/**
- * The wordmark, in the largest form this terminal can hold.
- *
- *   "full"    — the drawn mark, three rows, on a vertical gradient
- *   "compact" — the name in the accent, for a terminal too narrow for the art
- *               or a console without the half-block glyphs
- *   "plain"   — no escapes at all: a pipe, a CI log, NO_COLOR
- *
- * Returns the lines to print, blank lines included, so the caller writes them
- * and nothing else decides how much air the banner gets.
- */
-export function wordmark({
-  columns = 80, version = "0.0.0", profile = "none", unicode = true, pal = palette(profile),
-} = {}) {
-  const g = glyphs(unicode);
-  // Each layout asks for its own tagline, because each leaves it a different
-  // amount of room — see the prefix constants above.
-  const tag = (prefix) => tagline(version, columns, g.bullet, prefix);
-
-  if (profile === "none") return { kind: "plain", lines: ["", `  ccdeck ${tag(PLAIN_PREFIX_W)}`, ""] };
-  if (!unicode || columns < WORDMARK_WIDTH + 1) {
-    return { kind: "compact", lines: ["", `  ${pal.bold}${pal.accent}ccdeck${pal.reset}  ${pal.muted}${tag(COMPACT_PREFIX_W)}${pal.reset}`, ""] };
-  }
-
-  const ramp = [pal.accentSoft, pal.accent, pal.accentDeep];
-  return {
-    kind: "full",
-    lines: [
-      "",
-      ...WORDMARK_LINES.map((l, i) => `  ${ramp[i]}${l}${pal.reset}`),
-      "",
-      `  ${pal.muted}${tag(TAG_INDENT_W)}${pal.reset}`,
-      "",
-    ],
-  };
-}
-
-// ── the pulse line ───────────────────────────────────────────────────────────
-
-/**
- * The one line that stays on screen for hours, sized to the terminal it is on.
- *
- * It is redrawn over itself with `\r`, so both messages are padded to one width
- * — the shorter has to cover the longer — and that width is clamped to the real
- * terminal: at 40 columns the old 58-character message wrapped, after which the
- * `\r` only ever reached the second row and every repaint left the first one
- * behind. A deck no hook can find is not listening in any sense the user cares
- * about, which is why that state has a message here at all.
- *
- * `claude` is what makes that last sentence conditional. A deck watching only
- * Codex is not waiting on a hook: startCodexWatcher is started by startServer
- * and never consults the discovery file, and writesCodexLog keeps a deck with no
- * record on disk writing its log. Capture and persistence both work perfectly
- * there, while this line used to repaint "hooks cannot find this deck" every
- * 800ms, forever (#404) — a permanent alarm about a mechanism that deck does not
- * use. The one-time report at boot still says what IS lost; see
- * unregisteredDetail.
- */
-export function pulseText({
-  registered = true, claude = true, columns = 80, unicode = true, indent = 2, busy = null,
-} = {}) {
-  const g = glyphs(unicode);
-  const room = Math.max(4, columns - indent - 3 - 1);
-  const pick = (options) => options.find((o) => o.length <= room) ?? options[options.length - 1].slice(0, room);
-
-  const rest = pick([`listening ${g.dash} Ctrl+C to stop`, "listening"]);
-  const bad = pick([
-    `listening, but not registered ${g.dash} hooks cannot find this deck`,
-    `not registered ${g.dash} hooks cannot find this deck`,
-    "not registered",
-  ]);
-  // Both branches are still measured, registered or not, because the line is
-  // redrawn over itself and the shorter message has to cover the longer one on
-  // the beat after a deck loses its registration.
-  //
-  // The width is deliberately computed from the two FIXED messages only. `busy`
-  // comes and goes on a single boot — an install starts, the line names it, the
-  // install ends and the line goes back to Ctrl+C — so a width that grew to fit
-  // the label would have to shrink again afterwards, and the shorter line would
-  // leave the tail of the longer one on screen. Instead the label is shown only
-  // where it already fits — 60 columns and wider, measured — and below that the
-  // line says the true thing it has always said.
-  const width = Math.min(room, Math.max(rest.length, bad.length));
-  // What is still happening, rather than what is always true. `Ctrl+C to stop`
-  // is the right thing to say to somebody with nothing left to wait for, and
-  // the wrong thing to say to somebody watching an install.
-  const label = typeof busy === "string" && busy.trim() ? busy.trim() : null;
-  const working = label ? `listening ${g.bullet} ${label}` : null;
-  const ok = working && working.length <= width ? working : rest;
-  return (registered || !claude ? ok : bad).padEnd(width);
-}
-
-/**
- * Whether the line has anything left to say by moving.
- *
- * #742. The dot alternated green and grey every 800ms for as long as the deck
- * ran, and a blinking indicator beside a status line is the vocabulary of
- * "working on it" — so a boot that had finished in a second read as one that
- * never finished, and people said so. The deck's own web UI already retired
- * this once: the pill goes quiet at rest (#720). The terminal did not.
- *
- * Motion is now spent on the two states where something is genuinely
- * outstanding — a deck no hook can find, and a background job still running —
- * and nowhere else. At rest the dot is painted once, in the healthy colour, and
- * left alone. Movement then means something changed, which is the only thing
- * movement should ever mean on a line somebody leaves open for hours.
- */
-export function pulseMoves({ registered = true, claude = true, busy = null } = {}) {
-  if (!registered && claude) return true;
-  return typeof busy === "string" && busy.trim() !== "";
-}
-
-/**
- * Whether the dot is lit on this beat.
- *
- * `"on"` on every beat of a deck at rest, which is what makes the line still:
- * bin/deck.js paints a beat only when the frame differs from the one already on
- * screen, so a dot that is always lit is a line written once and then left
- * alone. Alternating is reserved for the states pulseMoves admits.
- *
- * The beat is a parameter rather than counted here so this is a function of its
- * inputs and nothing else — and so a test can ask what the twentieth beat of an
- * idle deck looks like without waiting sixteen seconds for it.
- */
-export function pulseDot(beat, { registered = true, claude = true, busy = null } = {}) {
-  if (!pulseMoves({ registered, claude, busy })) return "on";
-  return beat % 2 === 0 ? "on" : "off";
-}
-
-/**
- * The second line of the "not registered" report, which bin/deck.js prints once
- * per change of state rather than every beat.
- *
- * What a missing discovery file costs is not the same on the two capture paths,
- * and the old sentence — "hooks find this deck through <file>, so until that
- * file exists no events arrive" — stated the Claude Code answer as if it were
- * both. On a Codex-only deck it is false twice over: no hook is looking for this
- * deck, and events do keep arriving, because the rollout watcher reads the files
- * directly. What that deck really loses is the writer election in
- * log-writer.mjs, which is how several decks tailing one rollout agree on which
- * of them appends it to a shared events log. A deck with no record on disk is
- * assumed to be writing, so nothing is dropped — the log can gain the same line
- * twice instead.
- *
- * @param file the discovery file that could not be written.
- * @param claude whether this deck is watching Claude Code at all.
- * @param dash the em dash, or the ASCII stand-in on a console that cannot draw
- *   one (#797). A parameter for the same reason `renameNotice` takes one: this
- *   module's own header says "every glyph the deck prints — punctuation
- *   included, since an em dash is as absent from CP437 as a check mark — comes
- *   from one of them", and this sentence had it hardcoded. On a legacy cmd.exe
- *   or the Linux virtual console the reader got a box in the middle of the one
- *   line explaining why no events are arriving.
- */
-export function unregisteredDetail({ file, claude = true, dash = "—" }) {
-  if (claude) {
-    return `Claude Code hooks find this deck through ${file}, so until that file exists no Claude Code events arrive.`;
-  }
-  return `Codex capture does not use ${file} ${dash} the deck tails the rollout files itself ${dash} so events still arrive. Only decks sharing one events log need it, to agree on which of them records.`;
-}
-
-// ── cursor ───────────────────────────────────────────────────────────────────
-//
-// Strings rather than writers: hiding the cursor is trivial and restoring it is
-// not — it has to happen on the normal exit, on SIGINT/SIGTERM/SIGHUP and after
-// an uncaught throw, and getting that half-right leaves the user's shell with
-// no cursor after the deck is gone. The lifecycle owns it; see bin/deck.js.
-export const CURSOR_HIDE = "\x1b[?25l";
-export const CURSOR_SHOW = "\x1b[?25h";