sprag-cli 3.48.0 → 3.50.0

package/bin/cli.js

@@ -34,9 +34,13 @@ import {
   readStdinJson,
   extractCaps,
   extractContextUsage,
+  extractEffort,
   extractModel,
+  extractTranscriptPath,
 } from '../src/stdin-payload.js';
 
+import { effortChipLevel } from '../src/ultracode.js';
+
 import { parseAllSessions, getLastUserMessageTime } from '../src/parser.js';
 import {
   dailyTrend,
@@ -514,6 +518,9 @@ async function main() {
       const stdinJson = readStdinJson();
       const caps = extractCaps(stdinJson);
       const model = extractModel(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');
@@ -521,7 +528,7 @@ async function main() {
         } catch (e) { debug('caps-cache:persist', e); }
       }
       console.log(formatNoSession(
-        { caps, model, windowLabel, version: PKG_VERSION, update: readUpdateChip() },
+        { caps, model, effort, windowLabel, version: PKG_VERSION, update: readUpdateChip() },
         { color: colorOk, mode: labelMode },
       ));
       return;
@@ -567,6 +574,18 @@ async function main() {
   const stdinJson = readStdinJson();
   let caps = extractCaps(stdinJson);
   let model = extractModel(stdinJson);
+  // Not persisted to the caps cache the way caps/model are: the cache exists so
+  // 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.
+  //
+  // `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 {
@@ -758,6 +777,7 @@ async function main() {
     spikeChip,
     caps,
     model,
+    effort,
     delegationSaved,
     delegationTotals,
     doc2mdTotals,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sprag-cli",
-  "version": "3.48.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
@@ -208,6 +209,63 @@ function buildKoreanSeg(c, isIcon, verbose, g) {
   }
 }
 
+/**
+ * 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.
+ *
+ * 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) reads as `high`, which is what
+ * Claude Code resolves an unset effort to.
+ */
+const EFFORT_TONES = effortTones({ truecolor: TRUECOLOR });
+
+/**
+ * Effort chip builder — the level from Claude Code's stdin payload
+ * (`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"
+ * next to a model name would be anyone's guess.
+ */
+function buildEffortSeg(effort, c, isIcon, g) {
+  if (typeof effort !== 'string' || effort.length === 0) return null;
+  // `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. 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] : 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)}`;
+}
+
 /**
  * Version segment builder — "which copy of this tool am I looking at", plus
  * the upgrade nudge when a newer one has been published.
@@ -289,9 +347,10 @@ function buildCapWarnSeg(capWarn, c, isIcon, g, color, mode) {
  * The stdin payload (rate limits, model) is still live in that case, and a
  * 90%+ cap warning is exactly the kind of signal that must not disappear
  * just because the user has been idle past the window — so cap-warn,
- * harness, and model chips still render around the "no session data" note.
+ * harness, model, and effort chips still render around the "no session data"
+ * note.
  */
-export function formatNoSession({ caps = null, model = null, windowLabel = '', version = '', update = null } = {}, { color = true, mode = 'icon' } = {}) {
+export function formatNoSession({ caps = null, model = null, effort = null, windowLabel = '', version = '', update = null } = {}, { color = true, mode = 'icon' } = {}) {
   const c = (v) => (color ? v : '');
   // narrow shares the icon layout and swaps only the glyphs, so both modes take
   // the same branches from here on.
@@ -307,6 +366,8 @@ export function formatNoSession({ caps = null, model = null, windowLabel = '', v
   if (typeof model === 'string' && model.length > 0) {
     segs.push(isIcon ? `${c(MAGENTA)}${g.model} ${model}${c(RESET)}` : `${c(MAGENTA)}${model}${c(RESET)}`);
   }
+  const effortSeg = buildEffortSeg(effort, c, isIcon, g);
+  if (effortSeg) segs.push(effortSeg);
   segs.push(`${c(GRAY)}${g.hit} no session data${windowLabel ? ` · ${windowLabel}` : ''}${c(RESET)}`);
   if (versionSeg && !(update && update.available)) segs.push(versionSeg);
   return segs.join(' · ') + (color ? '\x1b[K' : '');
@@ -319,7 +380,7 @@ export function formatNoSession({ caps = null, model = null, windowLabel = '', v
  * @param {boolean} [opts.verbose=false] - longer layout with labels
  * @param {boolean} [opts.timer=true] - show TTL countdown segment
  * @param {'text'|'icon'} [opts.mode='text'] - label style. 'icon' uses 🧠 ⏳ 💰 instead of word labels.
- * @param {string[]|null} [opts.segments] - segments to render, in the order given. Names: cap-warn, spike, version, harness, korean, model, hit, ttl, month, saved, delegated, doc2md, ctx, period, `usage` (every rate-limit window), plus per-window keys (`five_hour`, `seven_day`, …). `5h`/`7d` are kept as aliases for back-compat. cap-warn and spike keep the lead regardless of where they appear. Null/undefined = all, in the default order.
+ * @param {string[]|null} [opts.segments] - segments to render, in the order given. Names: cap-warn, spike, version, harness, korean, model, effort, hit, ttl, month, saved, delegated, doc2md, ctx, period, `usage` (every rate-limit window), plus per-window keys (`five_hour`, `seven_day`, …). `5h`/`7d` are kept as aliases for back-compat. cap-warn and spike keep the lead regardless of where they appear. Null/undefined = all, in the default order.
  * @param {boolean} [opts.singleLine=false] - force the legacy one-line layout. By default, when the delegation ledger has lifetime savings, the routing totals lead on their own first line and everything else moves to line 2 (Claude Code renders multi-line statuslines; `--single-line` is the escape hatch for terminals that only show the first line).
  */
 /**
@@ -341,7 +402,7 @@ export const DEFAULT_SEGMENT_ORDER = [
   'cap-warn', 'spike',
   'usage', 'ctx',
   'ttl',
-  'model',
+  'model', 'effort',
   // Grouped by the timeframe each figure covers, because mixing them was the
   // problem: a lifetime total, a windowed rate and a calendar-month estimate sat
   // interleaved, with one window label at the end of the line that appeared to
@@ -359,7 +420,7 @@ export const DEFAULT_SEGMENT_ORDER = [
 ];
 
 export function formatReport(data, { color = true, verbose = false, timer = true, mode = 'text', segments = null, singleLine = false } = {}) {
-  const { summary, ttl, cost, options, lastActivity, contextWindow, ctxLive, spikeChip, caps, model } = data;
+  const { summary, ttl, cost, options, lastActivity, contextWindow, ctxLive, spikeChip, caps, model, effort } = data;
   const { hitRate } = summary;
 
   // Hit rate → color signal
@@ -711,6 +772,11 @@ export function formatReport(data, { color = true, verbose = false, timer = true
     }
   }
 
+  // Effort chip — how hard the session is being worked (`/effort`). It follows
+  // the model chip because it qualifies it: the same model answers differently
+  // at `low` and at `max`, and the pair is one glance.
+  const effortSeg = buildEffortSeg(effort, c, isIcon, g);
+
   // Always-on usage segments — what /usage shows in Claude Code, mirrored
   // to the statusline so the user doesn't have to slash-command for it.
   // Today the stdin payload exposes the 5h ("Current session") and 7-day
@@ -820,6 +886,7 @@ export function formatReport(data, { color = true, verbose = false, timer = true
       case 'harness':   return [harnessSeg];
       case 'korean':    return [koreanSeg];
       case 'model':     return [modelSeg];
+      case 'effort':    return [effortSeg];
       // Dropped when the same story already owns a headline line above, which
       // would otherwise repeat it on line 2.
       case 'delegated': return totalsLine ? [] : [delegateSeg];

package/src/glyphs.js

@@ -39,6 +39,13 @@ const ICON = {
   harness: '🅷',
   korean: '✍️',
   model: '🤖',
+  // Effort: a closer look at the same thing, which is what raising it buys.
+  // Width decided this as much as meaning. The obvious picks for "a level" are
+  // 🎚 and 🎛 (U+1F39A/1F39B), and both are East Asian Width N while every other
+  // glyph in this set is W — drawn from the color-emoji font they occupy two
+  // cells while being counted as one, and the line shifts on every repaint. 🔬
+  // is W, so it measures the same as its neighbours.
+  effort: '🔬',
   routing: '🔀',
   doc: '📄',
   hit: '🧠',
@@ -67,6 +74,7 @@ const NARROW = {
   harness: '⍟',   // circled star: a score out of five
   korean: '⌨',    // an input/typing convention rather than a hand
   model: '◈',
+  effort: '▲',    // a magnitude: how hard the turn is being worked
   routing: '⇉',   // sent down a different path
   doc: '≣',       // stacked lines: a page of text
   hit: '◉',       // bullseye: a cache hit

package/src/stdin-payload.js

@@ -14,6 +14,7 @@ import { readFileSync } from 'node:fs';
  * The blob shape (subset we consume):
  *   {
  *     "transcript_path": "...",
+ *     "effort": { "level": "high" },
  *     "rate_limits": {
  *       "five_hour":  { "used_percentage": 94, "resets_at": 1777099200 },
  *       "seven_day":  { "used_percentage": 7,  "resets_at": 1777521600 }
@@ -120,3 +121,42 @@ export function extractModel(stdinJson) {
   if (typeof m.id === 'string' && m.id) return m.id;
   return null;
 }
+
+/**
+ * The effort level the session is running at — what `/effort` sets.
+ *
+ * Claude Code 2.1.276 assembles the statusline payload with
+ * `...modelHasEffort(model) && { effort: { level: resolved } }`, so two facts
+ * follow. The level arrives already resolved against the session setting (the
+ * builder defaults it to `high` when nothing is set), which is why no default
+ * is applied here. And the key is dropped entirely for models that carry no
+ * effort setting at all (the claude-3 era, opus-4.0, opus-4.1), as it is on
+ * Claude Code builds older than the field itself — so a null means "nothing to
+ * show", never "something went wrong", and the chip simply does not render.
+ *
+ * A per-turn override (the transcript's `perTurnEffort`) is not visible here:
+ * the builder resolves the level without passing the per-turn argument, so what
+ * this returns is the session level even on a turn that ran at another one.
+ *
+ * Lowercased so the renderer can look a tone up by level; an unrecognised level
+ * still renders, just in the default tone.
+ */
+export function extractEffort(stdinJson) {
+  const level = stdinJson?.effort?.level;
+  if (typeof level !== 'string') return null;
+  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;
+}