sprag-cli 3.49.0 → 3.50.0

package/bin/cli.js

@@ -36,8 +36,11 @@ import {
   extractContextUsage,
   extractEffort,
   extractModel,
+  extractTranscriptPath,
 } from '../src/stdin-payload.js';
 
+import { effortChipLevel } from '../src/ultracode.js';
+
 import { parseAllSessions, getLastUserMessageTime } from '../src/parser.js';
 import {
   dailyTrend,
@@ -515,7 +518,9 @@ async function main() {
       const stdinJson = readStdinJson();
       const caps = extractCaps(stdinJson);
       const model = extractModel(stdinJson);
-      const effort = extractEffort(stdinJson);
+      // Resolved the same way as on the populated line below, so the chip does
+      // not change its mind about the level when the analysis window empties.
+      const effort = effortChipLevel(extractEffort(stdinJson), extractTranscriptPath(stdinJson));
       if (caps || model) {
         try {
           const { persistSnapshot } = await import('../src/caps-cache.js');
@@ -573,7 +578,14 @@ async function main() {
   // the table view (which pipes no stdin) can still show them, and a level the
   // user has since changed would be worse there than no chip at all. The effort
   // chip is a live-statusline reading only.
-  const effort = extractEffort(stdinJson);
+  //
+  // `ultracode` is the one level the payload cannot name — Claude Code raises it
+  // to xhigh and reports that — so the transcript settles which of the two this
+  // session is on. Only an xhigh payload can resolve to ultracode, so a session
+  // on any other level pays nothing for the check (see src/ultracode.js).
+  const effort = isStatusline
+    ? effortChipLevel(extractEffort(stdinJson), extractTranscriptPath(stdinJson))
+    : extractEffort(stdinJson);
   const ctxLive = extractContextUsage(stdinJson);
   if (isStatusline && (caps || model)) {
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sprag-cli",
-  "version": "3.49.0",
+  "version": "3.50.0",
   "description": "Sprag - a quality ratchet harness for AI coding agents: model-fitting delegation, ratchet rules, doc2md, Korean style gate. Same tool as claude-token-saver, under its new name.",
   "type": "module",
   "bin": {
@@ -13,6 +13,7 @@
     "postinstall": "node bin/cli.js install || true",
     "publish:legacy": "node scripts/publish-legacy.mjs",
     "release:notes": "node scripts/release-notes.mjs",
+    "site:docs": "node scripts/build-site-docs.mjs",
     "test": "node --test"
   },
   "files": [

package/src/effort-palette.js

@@ -0,0 +1,145 @@
+/**
+ * Effort palette — Claude Code's own colors for the effort levels.
+ *
+ * The statusline used to tint the effort chip from this tool's muted palette,
+ * which meant the level you picked in `/effort` and the level the chip reported
+ * were the same word in different colors. These are the app's values instead, so
+ * the chip echoes the color the picker showed.
+ *
+ * The mapping is not per-level color keys — Claude Code 2.1.276 keeps a slider
+ * table whose entries name SEMANTIC theme colors, which is why grepping for
+ * `effort*` keys finds only the last row:
+ *
+ *   lo=[{value:"low",   label:"low",   color:"warning"},
+ *       {value:"medium",label:"medium",color:"success"},
+ *       {value:"high",  label:"high",  color:"permission"},
+ *       {value:"xhigh", label:"xhigh", color:"autoAccept-shimmer"},
+ *       {value:"max",   label:"max",   color:"rainbow-animated"}]
+ *
+ * and ultracode is painted separately, in `effortUltra`:
+ *
+ *   function qCe(h){if(h){let E=Vre(Po("theme","dark").value);return bt("effortUltra",E)("ultracode")}}
+ *
+ * Two of those five are animated, and the statusline cannot animate: Claude Code
+ * re-runs the command on an interval measured in seconds (`statusLine.refreshInterval`,
+ * clamped to `Math.max(1,n)*1000`) and each run is a new process with no frame
+ * state, so a cycling color would read as a flicker rather than a shimmer. Both
+ * are therefore rendered as their still form — `xhigh` takes the `autoAccept`
+ * base color, and `max` takes the rainbow as a gradient across the word instead
+ * of a cycle over time.
+ *
+ * VALUES are lifted verbatim from the six theme tables in the 2.1.276 binary.
+ * `dark` is the default (`Po("theme","dark")`), where `autoAccept` and
+ * `effortUltra` are the same color: Claude Code separates `xhigh` from
+ * `ultracode` by shimmering one of them, not by hue.
+ *
+ * Dropping the animation would therefore leave the top two levels identical, so
+ * `ultracode` takes the shimmer's own two endpoints as a GLOW instead — a ramp
+ * from `autoAccept` up to `autoAcceptShimmer` and back down, spread across the
+ * word. Same device as `max`: what the app says over time, the chip says across
+ * the letters. No new colors are invented, and the level that costs the most is
+ * the one that looks lit.
+ *
+ * An 8-color terminal has no ramp to spend, so there `ultracode` stays the flat
+ * bright magenta and the level word is the only thing separating it from xhigh.
+ */
+
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/** The theme names Claude Code accepts, from its own settings enum. */
+export const THEME_NAMES = ['dark', 'light', 'light-daltonized', 'dark-daltonized', 'light-ansi', 'dark-ansi'];
+
+/** 24-bit values, per theme, for the four semantic keys the slider names. */
+const RGB = {
+  dark: { warning: [255, 193, 7], success: [78, 186, 101], permission: [177, 185, 249], autoAccept: [175, 135, 255], ultra: [175, 135, 255] },
+  light: { warning: [150, 108, 30], success: [44, 122, 57], permission: [87, 105, 247], autoAccept: [135, 0, 255], ultra: [135, 0, 255] },
+  'dark-daltonized': { warning: [255, 204, 0], success: [51, 153, 255], permission: [153, 204, 255], autoAccept: [175, 135, 255], ultra: [175, 135, 255] },
+  'light-daltonized': { warning: [255, 153, 0], success: [0, 102, 153], permission: [51, 102, 255], autoAccept: [135, 0, 255], ultra: [135, 0, 255] },
+};
+
+/**
+ * The 8-color forms, from Claude Code's two ANSI themes. These are what a
+ * terminal without 24-bit color gets, and they are also the whole palette for a
+ * user who picked an ANSI theme on purpose.
+ */
+const ANSI = {
+  dark: { warning: '\x1b[93m', success: '\x1b[92m', permission: '\x1b[94m', autoAccept: '\x1b[95m', ultra: '\x1b[95m' },
+  light: { warning: '\x1b[33m', success: '\x1b[32m', permission: '\x1b[34m', autoAccept: '\x1b[35m', ultra: '\x1b[35m' },
+};
+
+/**
+ * `autoAcceptShimmer` — the bright end of the pair Claude Code shimmers between,
+ * per theme. Only the dark/light split matters here, since the daltonized themes
+ * carry the same purple pair as their plain counterparts.
+ */
+const SHIMMER = {
+  dark: [208, 180, 255],
+  light: [208, 180, 255],
+  'dark-daltonized': [208, 180, 255],
+  'light-daltonized': [208, 180, 255],
+};
+
+/**
+ * The glow ramp for `ultracode`: base → shimmer → base, seven stops, so a word
+ * painted with it brightens toward the middle and settles again. Built by
+ * interpolation rather than hand-picked, so a theme whose purple differs still
+ * gets a smooth ramp.
+ */
+function glowRamp(base, peak) {
+  const t = [0, 1 / 3, 2 / 3, 1, 2 / 3, 1 / 3, 0];
+  return t.map((k) => base.map((ch, i) => Math.round(ch + (peak[i] - ch) * k)));
+}
+
+/** `max` — rainbow_red … rainbow_violet. One table for every theme. */
+const RAINBOW_RGB = [
+  [235, 95, 87], [245, 139, 87], [250, 195, 95], [145, 200, 130], [130, 170, 220], [155, 130, 200], [200, 130, 180],
+];
+/** Same seven, in the order the ANSI themes name them (red, redBright, yellow, green, cyan, blue, magenta). */
+const RAINBOW_ANSI = ['\x1b[31m', '\x1b[91m', '\x1b[33m', '\x1b[32m', '\x1b[36m', '\x1b[34m', '\x1b[35m'];
+
+const esc = ([r, g, b]) => `\x1b[38;2;${r};${g};${b}m`;
+
+/**
+ * The theme Claude Code is running, resolved the way it resolves it: the config
+ * value if set, `dark` otherwise. Read best-effort — an unreadable or absent
+ * config is the default theme, never an error, because this feeds a statusline.
+ */
+export function claudeTheme() {
+  for (const path of [join(homedir(), '.claude.json'), join(homedir(), '.claude', 'settings.json')]) {
+    try {
+      const raw = JSON.parse(readFileSync(path, 'utf8'));
+      const theme = raw && typeof raw.theme === 'string' ? raw.theme : null;
+      if (theme && THEME_NAMES.includes(theme)) return theme;
+    } catch { /* absent or malformed — keep looking, then default */ }
+  }
+  return 'dark';
+}
+
+/**
+ * Escapes for every effort level, keyed by level name. `max` is an ARRAY of
+ * escapes — one per rainbow stop — and every other level is a single escape, so
+ * a caller paints `max` character by character and the rest in one go.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.theme] - a Claude Code theme name; anything unknown reads as `dark`.
+ * @param {boolean} [opts.truecolor=true] - false emits the ANSI forms.
+ */
+export function effortTones({ theme = claudeTheme(), truecolor = true } = {}) {
+  const ansiTheme = theme.startsWith('light') ? 'light' : 'dark';
+  // An ANSI theme is a deliberate choice, so it wins over terminal capability.
+  const useAnsi = !truecolor || theme.endsWith('-ansi');
+  const keys = useAnsi ? ANSI[ansiTheme] : (RGB[theme] || RGB.dark);
+  const tone = (key) => (useAnsi ? keys[key] : esc(keys[key]));
+  return {
+    low: tone('warning'),
+    medium: tone('success'),
+    high: tone('permission'),
+    xhigh: tone('autoAccept'),
+    max: useAnsi ? RAINBOW_ANSI : RAINBOW_RGB.map(esc),
+    ultracode: useAnsi
+      ? keys.ultra
+      : glowRamp(keys.ultra, SHIMMER[theme] || SHIMMER.dark).map(esc),
+  };
+}

package/src/formatters/statusline.js

@@ -23,6 +23,7 @@ import { labelForKey } from '../window-labels.js';
 import { harnessStatusForStatusline } from '../harness.js';
 import { loadConfig } from '../config.js';
 import { koreanStyleEnabled } from '../korean-style.js';
+import { effortTones } from '../effort-palette.js';
 import { MIN_VOTES } from '../model-alias.js';
 
 // The 8-color ANSI defaults (RED=31, GREEN=32, YELLOW=33…) read as garish
@@ -209,35 +210,30 @@ function buildKoreanSeg(c, isIcon, verbose, g) {
 }
 
 /**
- * Effort tones. Claude Code resolves an unset effort to `high`, so `high` is the
- * level a session runs at when nobody has touched it — it gets the magenta
- * identity tone the model chip uses, and the two chips read as one group about
- * which model is answering and how hard. Levels below default recede to gray:
- * they spend less, and this tool has no business nagging about that.
+ * Effort tones are not this palette's to choose: they are Claude Code's own, so
+ * the chip shows a level in the color its `/effort` picker showed when the level
+ * was set. src/effort-palette.js holds the values and the evidence for them,
+ * including why `xhigh` and `ultracode` share a color once the shimmer that
+ * separates them in the app is dropped.
  *
- * The levels above default are the same magenta, bold. Not yellow, although
- * raising effort does buy quality with tokens per turn: yellow in this line is
- * the "you should do something eventually" tone (see buildVersionSeg), and an
- * effort level is a setting the user chose, not a state to fix. Someone who
- * pins `max` would read a permanently yellow chip as a standing complaint, and
- * a chip that is always warning-colored is how a line teaches the eye to skip
- * its warning color. Bold says "turned up" in the identity tone instead.
+ * This replaced a scheme of this tool's own devising (gray below default, the
+ * model chip's violet at default, bold above it). That scheme was internally
+ * tidy and still wrong in the only way that matters: the user picks a level in
+ * one UI and reads it back in another, and the two disagreed about what the
+ * level looks like. Matching the app also means the chip now uses yellow at
+ * `low`, which this line otherwise reserves for "act on this eventually" — a
+ * deliberate exception, since the color is quoting Claude Code rather than
+ * making a claim about the level.
  *
- * An unlisted level (a new one Anthropic ships) renders in the identity tone
- * rather than not at all.
+ * An unlisted level (a new one Anthropic ships) reads as `high`, which is what
+ * Claude Code resolves an unset effort to.
  */
-const EFFORT_TONES = {
-  none: GRAY,
-  low: GRAY,
-  medium: GRAY,
-  high: MAGENTA,
-  xhigh: BOLD + MAGENTA,
-  max: BOLD + MAGENTA,
-};
+const EFFORT_TONES = effortTones({ truecolor: TRUECOLOR });
 
 /**
  * Effort chip builder — the level from Claude Code's stdin payload
- * (`effort.level`, see extractEffort).
+ * (`effort.level`, see extractEffort), or `ultracode` when the entry point
+ * resolved that from the transcript (see effortChipLevel).
  *
  * The level is a word ("high"), so icon modes need no label beside the glyph:
  * `🔬 high` already reads. Text mode names the field, because a bare "high"
@@ -248,12 +244,26 @@ function buildEffortSeg(effort, c, isIcon, g) {
   // `hasOwn` rather than a bare index, for the reason model-alias.js gives at
   // its own lookup: the level is a string off a JSON payload, and a level of
   // 'constructor' or '__proto__' would resolve through Object.prototype to a
-  // function or an object. The `|| MAGENTA` fallback cannot catch that, since
-  // both are truthy — the tone would be interpolated as
+  // function or an object. A `||` fallback cannot catch that, since both are
+  // truthy — the tone would be interpolated as
   // `function Object() { [native code] }` and take the whole line with it.
-  const tone = Object.hasOwn(EFFORT_TONES, effort) ? EFFORT_TONES[effort] : MAGENTA;
-  if (isIcon) return `${c(tone)}${g.effort} ${effort}${c(RESET)}`;
-  return `${c(tone)}Effort ${effort}${c(RESET)}`;
+  const tone = Object.hasOwn(EFFORT_TONES, effort) ? EFFORT_TONES[effort] : EFFORT_TONES.high;
+  const head = isIcon ? `${g.effort} ` : 'Effort ';
+  // `max` arrives as the rainbow's seven stops (Claude Code cycles them; see
+  // effort-palette.js for why a statusline cannot). The stops are spread across
+  // the word rather than cycled through it: "max" is three characters, so
+  // cycling would show only the first three stops — red, orange, yellow, which
+  // reads as a warm gradient and not as a rainbow. Spreading walks the whole
+  // arc whatever the word's length.
+  if (Array.isArray(tone)) {
+    const chars = [...effort];
+    const last = Math.max(1, chars.length - 1);
+    const word = chars
+      .map((ch, i) => `${c(tone[Math.round((i * (tone.length - 1)) / last)])}${ch}`)
+      .join('');
+    return `${c(tone[0])}${head}${word}${c(RESET)}`;
+  }
+  return `${c(tone)}${head}${effort}${c(RESET)}`;
 }
 
 /**

package/src/stdin-payload.js

@@ -147,3 +147,16 @@ export function extractEffort(stdinJson) {
   const trimmed = level.trim();
   return trimmed === '' ? null : trimmed.toLowerCase();
 }
+
+/**
+ * The current session's transcript path, as Claude Code reports it.
+ *
+ * Read for one thing only: the effort chip's ultracode check, which the payload
+ * cannot answer on its own (see src/ultracode.js). Everything else about the
+ * current session comes from the analysis window, so a missing or non-string
+ * path is not worth a fallback — the caller simply skips the check.
+ */
+export function extractTranscriptPath(stdinJson) {
+  const path = stdinJson?.transcript_path;
+  return typeof path === 'string' && path !== '' ? path : null;
+}

package/src/ultracode.js

@@ -0,0 +1,202 @@
+/**
+ * Ultracode detection — the one effort level Claude Code does not put in the
+ * statusline payload.
+ *
+ * `/effort ultracode` is "xhigh + dynamic workflow orchestration, this session
+ * only". Claude Code stores it as two things: the effort level, which it raises
+ * to `xhigh`, and a session flag for the orchestration half. Only the level
+ * reaches the statusline contract (2.1.276 builds the payload as
+ * `...modelHasEffort(model) && { effort: { level: resolved } }`, where `resolved`
+ * is validated against the level list and so can never read "ultracode"), so a
+ * session on ultracode and a session on plain xhigh arrive here identical.
+ *
+ * What does distinguish them is in the transcript. Claude Code injects a
+ * system-reminder when ultracode turns on and another when it turns off, and
+ * both are recorded as attachment entries:
+ *
+ *   {"type":"attachment","attachment":{"type":"ultra_effort_enter","reminderType":"full"}}
+ *   {"type":"attachment","attachment":{"type":"ultra_effort_exit"}}
+ *
+ * The `enter` attachment repeats while ultracode stays on — once on the turn it
+ * is switched on ("full"), then every tenth user turn as a reminder ("sparse",
+ * TURNS_BETWEEN_MAINTENANCE = 10) — so the most recent of the two markers is
+ * the current state, and an active session keeps refreshing it near the tail.
+ *
+ * A marker is only written when the NEXT turn is assembled, though, so on its own
+ * it leaves the chip a turn behind: you run `/effort ultracode`, nothing has been
+ * recorded yet, and the chip still says xhigh until you send something. The
+ * command's own output closes that gap, because Claude Code writes it to the
+ * transcript the moment the command returns:
+ *
+ *   {"type":"user","message":{"content":"<local-command-stdout>Set effort level to
+ *    ultracode (this session only): xhigh + dynamic workflow orchestration</local-command-stdout>"}}
+ *
+ * measured 7s, 34s and 72s ahead of the matching attachment in one session. Both
+ * directions are legible there: the ultracode row is the only one that names the
+ * level, and every other `/effort <level>` clears the flag as it sets the level
+ * (`effortUpdate:{value:e,ultracode:!1}`), so those rows mean "off". The bare
+ * query prints `Current effort level: …`, which reads the same way.
+ *
+ * Hence the read below: walk backwards from the end of the transcript and take
+ * whichever of the two signals comes last. The scan is capped (see SCAN_BYTES)
+ * because the statusline re-renders every few seconds and most sessions carry
+ * neither signal — an uncapped backwards scan would read the whole transcript,
+ * every render, to answer "no". The cap makes the failure one-directional: past
+ * it we report "not ultracode", which is what the chip showed before this
+ * existed.
+ */
+
+import { openSync, readSync, closeSync, statSync } from 'node:fs';
+
+/**
+ * How far back to look for a marker. Measured against real transcripts: the
+ * gap between two consecutive markers of an ultracode session ran to 2.2MB
+ * (ten heavy turns), and the tail after the last one to 0.9MB. 4MB clears both
+ * with room, and costs a single bounded read of a file the renderer's own
+ * session parse has already pulled into the page cache.
+ */
+const SCAN_BYTES = 4 * 1024 * 1024;
+/**
+ * Substrings worth parsing a line for. The first is the attachment; the other
+ * two are the shapes `/effort` prints. Cheap prefilters only — every hit is
+ * parsed and checked before it counts.
+ */
+const MARKERS = ['ultra_effort_', 'Set effort level to', 'Current effort level:'];
+const NEWLINE = 0x0a;
+/** The levels Claude Code accepts; any of them being SET means ultracode is off. */
+const PLAIN_LEVELS = /Set effort level to (?:low|medium|high|xhigh|max)\b/;
+/** The bare query's answer, which names ultracode when it is on. */
+const QUERY_LEVEL = /Current effort level: (\w+)/;
+
+/**
+ * The state one transcript line carries, or null when it carries none.
+ *
+ * The line has to be parsed, not just matched: a transcript records tool output
+ * too, so a session that greps for these very strings (this feature was built
+ * in one) has lines that contain `ultra_effort_enter` as quoted text. Only an
+ * attachment entry of that type is a marker.
+ *
+ * Sidechain entries are skipped. A subagent runs its own effort resolution, so
+ * its reminder describes the subagent, not the session the chip is about.
+ */
+function markerState(line) {
+  let entry;
+  try {
+    entry = JSON.parse(line);
+  } catch {
+    return null;
+  }
+  if (!entry || typeof entry !== 'object') return null;
+  if (entry.isSidechain === true) return null;
+  const type = entry.attachment && entry.attachment.type;
+  if (type === 'ultra_effort_enter') return true;
+  if (type === 'ultra_effort_exit') return false;
+  return commandState(entry);
+}
+
+/**
+ * The state one `/effort` command output reports, or null when the entry is not
+ * one.
+ *
+ * The filter is narrow on purpose, because these phrases travel. In the session
+ * this was built in, "Set effort level to …" appears six times outside a real
+ * command output: three times in assistant text that quoted it and three in tool
+ * results that printed it. Requiring a user entry whose content is a plain
+ * string carrying the `<local-command-stdout>` wrapper excluded all six and kept
+ * all twelve real ones — a tool result's content is an array of blocks, and
+ * quoted prose is not a user entry at all.
+ *
+ * A cancelled picker writes `<local-command-stdout>Cancelled</local-command-stdout>`,
+ * which matches nothing here and correctly changes no state.
+ */
+function commandState(entry) {
+  if (entry.type !== 'user') return null;
+  const content = entry.message && entry.message.content;
+  if (typeof content !== 'string' || !content.includes('<local-command-stdout>')) return null;
+  if (content.includes('Set effort level to ultracode')) return true;
+  const query = content.match(QUERY_LEVEL);
+  if (query) return query[1] === 'ultracode';
+  if (PLAIN_LEVELS.test(content)) return false;
+  return null;
+}
+
+/**
+ * Is ultracode on, according to this transcript?
+ *
+ * @param {string|null|undefined} transcriptPath - `transcript_path` from the statusline payload.
+ * @param {object} [opts]
+ * @param {number} [opts.scanBytes=SCAN_BYTES] - how many trailing bytes to search.
+ * @returns {boolean|null} true/false from the newest marker, null when there is
+ *   none in range or the file cannot be read. Callers treat null as "not
+ *   ultracode"; it is kept distinct from false so a caller can tell "the
+ *   session turned it off" from "nothing said".
+ */
+export function ultracodeFromTranscript(transcriptPath, { scanBytes = SCAN_BYTES } = {}) {
+  if (typeof transcriptPath !== 'string' || transcriptPath === '') return null;
+  let size;
+  try {
+    size = statSync(transcriptPath).size;
+  } catch {
+    return null;
+  }
+  if (size === 0) return null;
+
+  const start = Math.max(0, size - scanBytes);
+  const buf = Buffer.alloc(size - start);
+  let fd;
+  try {
+    fd = openSync(transcriptPath, 'r');
+    readSync(fd, buf, 0, buf.length, start);
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined) try { closeSync(fd); } catch { /* already closed */ }
+  }
+
+  // Backwards by candidate rather than line by line: lastIndexOf is a memchr
+  // over the window, while splitting 4MB of JSONL into lines to walk the tail
+  // would allocate the whole transcript tail as strings on every render.
+  let from = buf.length;
+  while (from > 0) {
+    // The newest hit of any marker, so the attachment and the command output
+    // compete on position and the later one wins.
+    let hit = -1;
+    for (const marker of MARKERS) {
+      const at = buf.lastIndexOf(marker, from - 1, 'utf8');
+      if (at > hit) hit = at;
+    }
+    if (hit === -1) return null;
+    const lineStart = buf.lastIndexOf(NEWLINE, hit) + 1;
+    const nlAfter = buf.indexOf(NEWLINE, hit);
+    const lineEnd = nlAfter === -1 ? buf.length : nlAfter;
+    // A window that starts mid-line leaves its first line truncated; that line
+    // fails to parse and is skipped like any other non-marker.
+    const state = markerState(buf.toString('utf8', lineStart, lineEnd));
+    if (state !== null) return state;
+    if (lineStart === 0) return null;
+    from = lineStart;
+  }
+  return null;
+}
+
+/**
+ * The level the effort chip should name.
+ *
+ * Reads the transcript only when the payload says `xhigh`, since that is the
+ * only level ultracode can present as — which keeps every other session, and
+ * every non-statusline caller, at zero extra I/O.
+ *
+ * The `xhigh` guard is also what keeps a stale marker honest. Dropping effort
+ * (say `/effort medium`) turns ultracode off, but the `exit` marker is only
+ * written when the next turn is assembled, so between those two moments the
+ * newest marker still says `enter` while the payload already says `medium`.
+ * Trusting the level here means the chip follows the payload, not the lag.
+ *
+ * @param {string|null} level - the level from the payload (see extractEffort).
+ * @param {string|null|undefined} transcriptPath
+ * @returns {string|null} `'ultracode'`, or `level` unchanged.
+ */
+export function effortChipLevel(level, transcriptPath) {
+  if (level !== 'xhigh') return level;
+  return ultracodeFromTranscript(transcriptPath) === true ? 'ultracode' : level;
+}