claude-code-runrate 0.3.0 → 0.5.0

package/src/pane-config.js

@@ -64,8 +64,14 @@ function configPath(env) {
  */
 function resolvePanePath(p, baseDir, home) {
   let out = p;
+  // `~\` as well as `~/`: a Windows user writes the separator their shell shows
+  // them, and accepting only the forward slash left `~\tools\blob.json` to
+  // resolve against the config directory — a path that cannot exist, whose only
+  // symptom is a pane that never appears. The tilde means home on the machine
+  // the config was written for; the separator it is followed by does not
+  // change that.
   if (out === '~') out = home;
-  else if (out.startsWith('~/')) out = path.join(home, out.slice(2));
+  else if (out.startsWith('~/') || out.startsWith('~\\')) out = path.join(home, out.slice(2));
   return path.resolve(baseDir, out);
 }
 
@@ -75,22 +81,50 @@ function resolvePanePath(p, baseDir, home) {
  * economy sidebar exactly as before this feature existed.
  *
  * @param {{ env?: Record<string, string|undefined>, home?: string }} [opts]
- * @returns {{ panes: Array<{ path: string, source: string }>, configPath: string }}
+ * @returns {{ panes: Array<{ path: string, source: string }>, configPath: string,
+ *   error: string|null }}
  *   `path` is absolute and ready to read; `source` is the string the user wrote
  *   (what error states name, so the message matches their config, not ours).
+ *   `error` names why a config that EXISTS produced no panes. A config that is
+ *   simply absent is not an error — that is most users — but one the user wrote
+ *   and got wrong must say so somewhere, or the only symptom of a typo is panes
+ *   that never appear.
  */
 function loadPaneConfig(opts = {}) {
   const env = opts.env || process.env;
   const home = opts.home || os.homedir();
   const file = configPath(env);
-  const empty = { panes: [], configPath: file };
+  const empty = { panes: [], configPath: file, error: null };
 
   const raw = readTextCapped(file, MAX_CONFIG_BYTES);
   if (raw == null || !raw.trim()) return empty;
 
+  // A UTF-8 byte-order mark makes JSON.parse throw. PowerShell writes one by
+  // default — `Set-Content`, `Out-File`, and `>` under Windows PowerShell all
+  // do — so a config written the obvious way on Windows is malformed on
+  // arrival, and the only symptom is panes that never appear. Strip it rather
+  // than diagnose it later: there is no config for which a leading BOM is
+  // content. (`.trim()` above already treats a BOM-only file as empty; U+FEFF
+  // is whitespace to the trimmer but not to the parser.)
+  const text = raw.replace(/^\uFEFF/, '');
+
+  // UTF-16 is the likelier Windows mistake, and it is NOT what the strip above
+  // catches. Windows PowerShell 5.1 writes UTF-16LE for `>` and `Out-File` by
+  // default (Set-Content writes ANSI; only `-Encoding utf8` gives the UTF-8 BOM;
+  // PowerShell 7+ writes UTF-8 without one). Read as UTF-8 those bytes survive
+  // trim() and reach the parser as a leading U+FFFD pair and NUL-interleaved
+  // text, so the parse fails and the honest-looking report is "not valid JSON"
+  // — sending someone to hunt for a syntax error in a file whose syntax is
+  // fine. A NUL is never content in a JSON config, so it names the real cause.
+  if (text.includes('\u0000')) {
+    return { ...empty, error: 'looks like UTF-16 — save it as UTF-8' };
+  }
+
   let parsed;
-  try { parsed = JSON.parse(raw); } catch { return empty; }
-  if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.panes)) return empty;
+  try { parsed = JSON.parse(text); } catch { return { ...empty, error: 'not valid JSON' }; }
+  if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.panes)) {
+    return { ...empty, error: 'no panes array' };
+  }
 
   const baseDir = path.dirname(file);
   /** @type {Array<{ path: string, source: string }>} */
@@ -103,7 +137,7 @@ function loadPaneConfig(opts = {}) {
     if (!source.trim()) continue;
     panes.push({ path: resolvePanePath(source, baseDir, home), source });
   }
-  return { panes, configPath: file };
+  return { panes, configPath: file, error: null };
 }
 
 module.exports = { loadPaneConfig, configPath, resolvePanePath, MAX_CONFIG_BYTES };

package/src/render/economy.js

@@ -10,16 +10,23 @@
 const { clearROI } = require('../burn');
 const { classifyWindows, band } = require('../economy-model');
 const { resolveTheme, lexicon } = require('../theme');
-const { dim, bold, green, red, yellow, cyan, flash, pctColor, bar, tok, fmtMins, fmtReset } = require('./shared');
+const { dim, bold, green, red, yellow, cyan, flash, pctColor, CRIT_PCT, usedLabel, bar, tok, fmtMins, fmtReset } = require('./shared');
+const { liveness } = require('../liveness');
 
 const bandColor = { imminent: red, warn: yellow, ok: cyan };
 
-function wallRow(/** @type {any} */ row, /** @type {any} */ L, /** @type {boolean} */ tick, /** @type {number} */ labelW) {
+function wallRow(/** @type {any} */ row, /** @type {any} */ L, /** @type {boolean} */ tick, /** @type {number} */ labelW, /** @type {boolean} */ stale, /** @type {number} */ numW) {
   // Truncate, don't round: Claude's own surfaces (`/usage`, claude.ai usage)
   // floor the fractional `used_percentage` (e.g. 41.6 → "41%"). Math.round here
   // read ~1pt high on values past the half-point. Display only — the burn/ROI
   // math below still uses the raw fractional `row.est.usedPct`.
+  //
+  // `used` (whole %) drives the bar fill and the colour band; `usedTxt` is the
+  // number actually shown, which gains one truncated decimal in the critical
+  // zone. Both floor, so they can never disagree about which side of a whole
+  // number the reading falls on.
   const used = Math.floor(row.est.usedPct);
+  const usedTxt = usedLabel(row.est.usedPct);
   const ml = row.est.minutesLeft;
   const b = band(ml);
   // Per-row colour dot: green when the window resets before you'd hit it,
@@ -37,7 +44,11 @@ function wallRow(/** @type {any} */ row, /** @type {any} */ L, /** @type {boolea
   const leftTxt = (ml != null ? '~' + fmtMins(ml) : '—').padEnd(7);
   const left = row.binding ? bold(leftTxt) : dim(leftTxt);
   const resets = row.reset != null ? dim('resets ' + fmtReset(row.reset)) : '';
-  const meter = pctColor(used)(bar(used)) + ' ' + String(used).padStart(2) + '% used';
+  // A stale snapshot dims the figure so a number frozen between chat rounds
+  // never reads as live. The bar colour stays, so the band still pops, and the
+  // sidecar appends the "updated …" note that says why (see src/liveness.js).
+  const numTxt = usedTxt.padStart(numW) + '% used';
+  const meter = pctColor(used)(bar(used)) + ' ' + (stale ? dim(numTxt) : numTxt);
   const main = '  ' + dot + ' ' + label + ' ' + left + ' ' + meter + '  ' + resets;
 
   // The binding window's "wall" call-out drops to its own indented line below —
@@ -51,16 +62,30 @@ function wallRow(/** @type {any} */ row, /** @type {any} */ L, /** @type {boolea
 
 /**
  * @param {any} view normalized economy data
- * @param {{ theme?: 'plain'|'mary', now?: Date, tick?: boolean, env?: any }} [opts]
+ * @param {{ theme?: 'plain'|'mary', now?: Date, tick?: boolean, env?: any,
+ *   ageMs?: number, staleMs?: number }} [opts]
+ *   ageMs/staleMs: how old the captured snapshot is, and the threshold past
+ *   which it counts as stale. The snapshot only refreshes per chat round, so
+ *   between rounds it ages — past the threshold the used figures dim, so they
+ *   read as last-known rather than live. The threshold decision itself stays
+ *   in src/liveness.js, which also owns the "updated …" note the sidecar
+ *   appends; this renderer only asks whether the data is stale.
  * @returns {string}
  */
 function renderEconomy(view, opts = {}) {
   const themeName = opts.theme || resolveTheme(opts.now, opts.env);
   const L = lexicon(themeName);
   const tick = !!opts.tick;
+  const stale = !!liveness({ ageMs: opts.ageMs ?? 0, staleMs: opts.staleMs }).marker;
   const out = [bold('economy') + dim('   ' + (view.model || '')), ''];
 
   const { rows, next } = classifyWindows(view);
+  // The used% column widens to fit a decimal only when some row actually has
+  // one. Widening it unconditionally would shift every meter two columns right
+  // for the whole time you are nowhere near the wall — which both costs a
+  // narrow sidebar two columns it needs and blunts the point of the decimal,
+  // whose appearing is itself the "you are in the zone" cue.
+  const numW = rows.some((/** @type {any} */ r) => r.est.usedPct >= CRIT_PCT && r.est.usedPct < 100) ? 4 : 2;
   // Cap the label column. `labelW` multiplies: every row pads to it, so cost is
   // rows × longest-label, and BOTH come from the snapshot's rate_limits keys. A
   // planted file with many buckets and one very long key built a string large
@@ -86,7 +111,7 @@ function renderEconomy(view, opts = {}) {
   }
   out.push('');
 
-  for (const r of rows) out.push(wallRow(r, L, tick, labelW));
+  for (const r of rows) out.push(wallRow(r, L, tick, labelW, stale, numW));
   if (rows.length) out.push('');
 
   // CLEAR — plain language, framed against the binding wall, only when it looms.

package/src/render/git-pane.js

@@ -0,0 +1,345 @@
+// @ts-check
+'use strict';
+// src/render/git-pane.js — draw the git pane from a model src/git-repo.js built.
+//
+// Same split as src/pane-blob.js → src/render/pane.js: the reader is the choke
+// point that sanitizes and caps, so this file does no validation and no
+// stripping. Every string arriving here is already printable. What it does own
+// is LAYOUT, and the one layout rule the contract actually pins is that a value
+// too long for the pane is shortened rather than wrapped — a wrapped line
+// corrupts the sidecar's cursor-home redraw (the reason clampVisible exists).
+//
+// The identity line is the pane's whole point: features/git-repo-identity.feature
+// exists because six tabs each labelled with an instance name say nothing about
+// which repo they sit in. So it is the first row, it is always exactly one row,
+// and it budgets its own space rather than letting a long branch name push the
+// repo name off the end.
+
+const {
+  dim, bold, cyan, green, red, yellow, clampVisible, visibleWidth, ellipsize, charWidth,
+} = require('./shared');
+
+// Left margin, matching every other ccr surface.
+const INDENT = '  ';
+
+// Fallback width when the caller knows nothing (non-TTY, `ccr sidecar` piped).
+// Same default the external pane renderer uses.
+const DEFAULT_WIDTH = 48;
+
+// The launch repo gets its OWN ROW, and this is a contract detail rather than a
+// layout preference. The option the visionary chose at scoping was "Follows,
+// with the launch repo pinned — shows the current repo, but ALWAYS keeps the
+// launch repo visible AS A SECOND LINE, so the tab keeps a stable identity while
+// the pane tracks the work" (features/OUT-OF-SCOPE.md, Roads not taken).
+//
+// An earlier build put it inline as "launch › current" and had to invent a rule
+// for dropping it when the row got tight — which meant a repo with a long branch
+// name silently lost the pinned identity the option promises to keep. A second
+// row cannot be crowded out by a branch name.
+const LAUNCH_PREFIX = 'launched in ';
+
+/**
+ * Lay two values out on one line: `left` at the margin, `right` flushed to the
+ * end, at least `gap` columns between them. When they do not both fit, each
+ * gets what it needs up to a fair half and the remainder goes to the other, so
+ * a short name never costs a long one room it could have used.
+ *
+ * @param {string} left
+ * @param {string} right
+ * @param {number} avail  Columns available to left + gap + right.
+ * @param {number} gap
+ * @returns {{ left: string, right: string, pad: number }}
+ */
+function fitPair(left, right, avail, gap) {
+  const room = Math.max(0, avail - gap);
+  const wl = visibleWidth(left);
+  const wr = visibleWidth(right);
+  if (wl + wr <= room) return { left, right, pad: room - wl - wr + gap };
+  const half = Math.floor(room / 2);
+  let bl;
+  let br;
+  if (wl <= half) { bl = wl; br = room - wl; } else if (wr <= half) { br = wr; bl = room - wr; } else { bl = room - half; br = half; }
+  return { left: ellipsize(left, bl), right: ellipsize(right, br), pad: gap };
+}
+
+/**
+ * The identity row — one row, always, whatever the model says.
+ *
+ * The position marker arrives as PLAIN text and is coloured here, deliberately.
+ * Passing it in pre-coloured is the obvious shape and it is wrong: visibleWidth
+ * counts display characters and knows nothing about SGR, so a dimmed "  2/2"
+ * measures 13 columns instead of 5 and quietly steals eight from the names.
+ * That version rendered fine at 48 columns and collapsed to "c…  …" at 20 —
+ * a layout bug that only appears off the demo path.
+ *
+ * @param {import('../git-repo').RepoIdentity} id
+ * @param {number} width     Total columns the row may occupy, marker included.
+ * @param {string} position  Plain cycle position, e.g. "2/3" (may be '').
+ * @returns {string}
+ */
+function identityLine(id, width, position) {
+  const markerText = position ? '  ' + position : '';
+  const marker = markerText ? dim(markerText) : '';
+  const avail = Math.max(1, width - visibleWidth(INDENT) - visibleWidth(markerText));
+
+  // ONE layout for every state. The right-hand slot holds the branch when there
+  // is one and the state's own sentence when there is not, so a repository whose
+  // HEAD cannot be read still gets NAMED on the left — the pane's entire job.
+  // An earlier version early-returned on any non-ok state and threw the name
+  // away, though the model had it.
+  //
+  // The two failure sentences stay distinct: "not a git repository" is a fact
+  // about the directory, and features/git-pane-safety.feature separately
+  // requires that a repo whose data cannot be READ says so instead. Conflating
+  // them would report a broken clone as a scratch directory.
+  const right = id.state === 'unreadable'
+    ? { text: 'git data unavailable', paint: yellow }
+    : id.state !== 'ok'
+      ? { text: 'not a git repository', paint: dim }
+      // Before `detached`, because it is the larger fact: a bare repository has
+      // no working tree, so there is no checkout for a branch name to describe
+      // and nothing for the working-tree section to ever show. "bare", not
+      // "empty" — `git init --bare` then push a thousand commits and it is
+      // still bare, so "empty" would be a different claim, and a false one.
+      : id.bare
+        ? { text: 'bare repository', paint: yellow }
+        : id.detached
+          ? { text: 'detached', paint: yellow }
+        // The `|| ''` is a type guard, not a case: readHead returns either a
+        // non-empty branch or detached: true, so an ok state with a null branch
+        // cannot occur. It stays because `branch` is nullable in the model and
+        // strict mode is right to insist the reader handle that.
+        : { text: id.branch || '', paint: cyan };
+
+  // Nothing to name on the left — the row is the sentence alone, which is what
+  // "the pane shows no branch name" pins for a plain scratch directory. The
+  // launch repo, if there is one, is a separate row and does not appear here.
+  if (!id.name) return INDENT + right.paint(right.text) + marker;
+
+  const leftPlain = id.name;
+  const leftColored = bold(id.name);
+  const fit = fitPair(leftPlain, right.text, avail, 2);
+  // Re-apply colour only when the plain text survived intact; a shortened value
+  // is rebuilt from the fitted string, so the ellipsis lands inside the colour
+  // run rather than after it.
+  const leftOut = fit.left === leftPlain ? leftColored : bold(fit.left);
+  const rightOut = fit.right === right.text ? right.paint(right.text) : right.paint(fit.right);
+  return INDENT + leftOut + ' '.repeat(Math.max(1, fit.pad)) + rightOut + marker;
+}
+
+// ── The working-tree section ────────────────────────────────────────────────
+//
+// Sits between the identity rows and the commit graph, which is why its row
+// budget is a stated formula rather than "whatever fits": the flat file list
+// and the graph compete for the same rows (features/git-working-tree.feature's
+// header says so), and the cap is the contract's answer to that competition.
+
+// Rows always reserved for the commit graph below the list, so a long file
+// list can never starve history off the pane entirely.
+const GRAPH_RESERVE = 8;
+
+// The section's own chrome: the counts row, the possible rebase row, the
+// possible "N more" row, and the blank line above the section.
+const WT_CHROME = 4;
+
+// A ceiling regardless of pane height: past this many file rows the list stops
+// informing and starts scrolling the reader.
+const WT_MAX_FILE_ROWS = 16;
+
+/**
+ * How many file rows the working-tree list may use in a pane `rows` tall.
+ * Exported because it IS the contract the long-list scenario names ("the pane
+ * has room for 8 file rows") — the steps derive the pane height from this
+ * formula rather than duplicating the arithmetic.
+ * @param {number} rows
+ * @returns {number}
+ */
+function fileRowBudget(rows) {
+  return Math.max(2, Math.min(WT_MAX_FILE_ROWS, Math.trunc(rows) - GRAPH_RESERVE - WT_CHROME));
+}
+
+/**
+ * Shorten from the FRONT, keeping the tail — the working-tree list's rule,
+ * because the tail is the file name and the file name is the answer ("A path
+ * too long for the pane keeps its file name"). The mirror of ellipsize.
+ * @param {string} s
+ * @param {number} cols
+ * @returns {string}
+ */
+function ellipsizeStart(s, cols) {
+  if (cols <= 0) return '';
+  if (visibleWidth(s) <= cols) return s;
+  if (cols === 1) return '…';
+  const cps = [...s];
+  let used = 1; // the ellipsis
+  let start = cps.length;
+  while (start > 0) {
+    const w = charWidth(/** @type {number} */(cps[start - 1].codePointAt(0)));
+    if (used + w > cols) break;
+    used += w;
+    start -= 1;
+  }
+  return '…' + cps.slice(start).join('');
+}
+
+/** @type {Record<import('../git-working-tree').ChangeMark, (s: string) => string>} */
+const MARK_PAINT = { '!': red, '+': green, M: yellow, '?': dim };
+
+/**
+ * The working-tree rows: counts, the capped file list, the remainder.
+ *
+ * @param {import('../git-working-tree').WorkingTree} wt
+ * @param {{ width: number, rows: number }} opts
+ * @returns {string[]}
+ */
+function workingTreeLines(wt, opts) {
+  const { width } = opts;
+  if (wt.state !== 'ok') return [INDENT + yellow('git data unavailable')];
+
+  /** @type {string[]} */
+  const lines = [];
+  // The rebase banner leads: it is the state that explains every "!" below it.
+  if (wt.rebase) lines.push(INDENT + yellow('rebase in progress'));
+
+  const total = wt.entries.length;
+  if (total === 0) {
+    if (!wt.rebase) lines.push(INDENT + dim('clean'));
+    return lines;
+  }
+  // `truncated` means the untracked walk hit its visit budget, so `total` is a
+  // floor rather than the count; the "+" keeps the headline honest.
+  lines.push(INDENT + (total === 1 && !wt.truncated ? '1 change' : `${total}${wt.truncated ? '+' : ''} changes`));
+
+  const budget = fileRowBudget(opts.rows);
+  const listed = wt.entries.slice(0, budget);
+  // Columns for the path: margin, one mark column, one space.
+  const pathCols = Math.max(1, width - visibleWidth(INDENT) - 2);
+  for (const e of listed) {
+    lines.push(INDENT + MARK_PAINT[e.mark](e.mark) + ' ' + ellipsizeStart(e.path, pathCols));
+  }
+  const rest = total - listed.length;
+  if (rest > 0) lines.push(INDENT + dim(`${rest}${wt.truncated ? '+' : ''} more`));
+  return lines;
+}
+
+// ── The commit graph ────────────────────────────────────────────────────────
+
+// One column per lane; the rest of a graph row is margin, hash, subject, age.
+// Reserving this much keeps a readable subject at every lane count the budget
+// can return.
+const LANE_RESERVE = 26;
+const MAX_LANES = 6;
+
+/**
+ * How many lanes a pane `width` columns wide may draw. Exported for the same
+ * reason as fileRowBudget: "the pane has room for 3 lanes" is a fact about
+ * THIS formula, and the steps derive the width from it.
+ * @param {number} width
+ * @returns {number}
+ */
+function laneBudget(width) {
+  return Math.max(1, Math.min(MAX_LANES, Math.trunc(width) - LANE_RESERVE));
+}
+
+/**
+ * A relative age: "now", then minutes, hours, days. Coarse on purpose — the
+ * scenario pins that an age is SHOWN, and a graph is not a clock.
+ * @param {number} whenSec
+ * @param {number} nowMs
+ * @returns {string}
+ */
+function fmtAge(whenSec, nowMs) {
+  const s = Math.max(0, Math.floor(nowMs / 1000) - whenSec);
+  if (s < 90) return 'now';
+  if (s < 90 * 60) return Math.round(s / 60) + 'm';
+  if (s < 36 * 3600) return Math.round(s / 3600) + 'h';
+  return Math.round(s / 86400) + 'd';
+}
+
+/**
+ * The graph rows: lane cells, short hash, subject, age — plus the overflow
+ * count when branches outnumber lanes.
+ *
+ * @param {import('../git-history').History} history
+ * @param {{ width: number, maxRows: number, now: number }} opts
+ * @returns {string[]}
+ */
+function commitGraphLines(history, opts) {
+  const { width } = opts;
+  if (history.state === 'unavailable') return [INDENT + yellow('git data unavailable')];
+  if (history.state === 'empty') return [INDENT + dim('no commits yet')];
+
+  /** @type {string[]} */
+  const lines = [];
+  const span = Math.max(1, history.laneCount);
+  for (const row of history.rows.slice(0, Math.max(1, opts.maxRows))) {
+    let cells = '';
+    for (let i = 0; i < span; i += 1) {
+      if (i === row.lane) cells += '●';
+      else if (row.joinLanes && row.joinLanes.includes(i)) cells += '╮';
+      else cells += (row.activeMask && row.activeMask[i]) ? '│' : ' ';
+    }
+    const age = fmtAge(row.when, opts.now);
+    // Margin + cells + space + hash + space + subject + gap + age = width.
+    const subjCols = Math.max(1,
+      width - visibleWidth(INDENT) - span - 1 - row.shortHash.length - 1 - 2 - visibleWidth(age));
+    const subject = ellipsize(row.subject, subjCols);
+    lines.push(INDENT + cyan(cells) + ' ' + dim(row.shortHash) + ' ' + subject
+      + '  ' + dim(age));
+  }
+  if (history.droppedBranches > 0) {
+    lines.push(INDENT + dim(`${history.droppedBranches} more branches`));
+  }
+  return lines;
+}
+
+/**
+ * Render the whole git pane.
+ *
+ * @param {{ identity: import('../git-repo').RepoIdentity,
+ *           workingTree?: import('../git-working-tree').WorkingTree,
+ *           history?: import('../git-history').History }} model
+ * @param {{ width?: number, position?: string, rows?: number, now?: number }} [opts]
+ * @returns {string}
+ */
+function renderGitPane(model, opts = {}) {
+  const width = opts.width && opts.width > 0 ? opts.width : DEFAULT_WIDTH;
+  const rows = opts.rows && opts.rows > 0 ? opts.rows : 24;
+  const id = model.identity;
+  const lines = [identityLine(id, width, opts.position || '')];
+  // The pinned launch repo: its own row, shown only when it differs from the
+  // repo the session is in — a tab that names the same repo twice has told the
+  // reader nothing, and the row costs vertical space the graph wants.
+  if (id.launchName) {
+    lines.push(INDENT + dim(ellipsize(LAUNCH_PREFIX + id.launchName, Math.max(1, width - visibleWidth(INDENT)))));
+  }
+  // The body sections render only where a working tree can exist: a located,
+  // readable, non-bare repository. Everywhere else the identity row already
+  // carries the pane's whole sentence.
+  const bodied = id.state === 'ok' && !id.bare;
+  if (model.workingTree && bodied) {
+    lines.push('');
+    lines.push(...workingTreeLines(model.workingTree, { width, rows }));
+  }
+  // The graph sits below the list — and is skipped when the working tree
+  // already degraded, so "git data unavailable" is said once, not twice from
+  // two sections that failed to read the same store.
+  if (model.history && bodied && (!model.workingTree || model.workingTree.state === 'ok')) {
+    lines.push('');
+    lines.push(...commitGraphLines(model.history, {
+      width,
+      maxRows: Math.max(3, rows - lines.length - 1),
+      now: opts.now != null ? opts.now : 0,
+    }));
+  }
+  // clampVisible is the net, not the mechanism: identityLine already budgets to
+  // `width`. It stays because a layout bug must cost a truncated line, never
+  // the wrap that corrupts the redraw.
+  return lines.map((l) => clampVisible(l, width)).join('\n');
+}
+
+module.exports = {
+  renderGitPane, identityLine, fitPair, workingTreeLines, commitGraphLines,
+  fileRowBudget, laneBudget, ellipsizeStart, fmtAge,
+  GRAPH_RESERVE, WT_MAX_FILE_ROWS, MAX_LANES,
+};

package/src/render/shared.js

@@ -16,6 +16,26 @@ const flash = (/** @type {boolean} */ tick, /** @type {string} */ s) => (tick ?
 
 const pctColor = (/** @type {number} */ p) => (p >= 75 ? red : p >= 60 ? yellow : green);
 
+// At/above this used%, surface one extra digit of Claude's own (fractional)
+// `used_percentage`. Near the wall the next tenth is a decision input; below it
+// it is noise. A decimal appearing IS the "you are in the zone" salience signal.
+const CRIT_PCT = 95;
+
+/**
+ * Used% display string. Below the critical zone: the whole number. In the zone
+ * (and under 100): one TRUNCATED decimal — the same downward direction as the
+ * integer floor, so `floor(shown)` still equals what `/usage` reports. We never
+ * tick above Claude's own number, only out-resolve it. The +1e-9 guards float
+ * representation: 98.7 * 10 is 986.9999… and would otherwise truncate to 98.6.
+ * @param {number} pct raw fractional used_percentage
+ * @returns {string}
+ */
+function usedLabel(pct) {
+  if (pct < CRIT_PCT || pct >= 100) return String(Math.floor(pct));
+  const tenths = Math.floor(pct * 10 + 1e-9);
+  return `${Math.floor(tenths / 10)}.${tenths % 10}`;
+}
+
 function bar(/** @type {number} */ p, w = 10) {
   const f = Math.max(0, Math.min(w, Math.round((p / 100) * w)));
   return '▓'.repeat(f) + '░'.repeat(w - f);
@@ -140,4 +160,52 @@ function fmtReset(/** @type {number|null} */ min) {
   return `${m}m`;
 }
 
-module.exports = { e, dim, bold, green, red, yellow, cyan, flash, pctColor, bar, clampVisible, tok, fmtMins, fmtReset };
+/**
+ * Terminal columns a PLAIN string occupies — the same accounting `clampVisible`
+ * does, exposed for the callers that must budget space before they build a line
+ * rather than clamp one afterwards. No SGR handling: the strings measured here
+ * are display text before any colour is applied.
+ * @param {string} s
+ * @returns {number}
+ */
+function visibleWidth(s) {
+  let w = 0;
+  for (const ch of s) w += charWidth(/** @type {number} */ (ch.codePointAt(0)));
+  return w;
+}
+
+/**
+ * Fit plain text into `cols` columns, marking the cut with an ellipsis so a
+ * shortened value never reads as a complete one. Cutting is by code point and
+ * by COLUMN (a wide glyph costs two), and the ellipsis is inside the budget —
+ * the result is never wider than `cols`.
+ *
+ * Distinct from `clampVisible`, which is the hard safety net applied to a
+ * finished line: this one is composition, so the caller can lay out around a
+ * value it knows will fit. Returns '' for a non-positive budget.
+ *
+ * @param {string} s
+ * @param {number} cols
+ * @returns {string}
+ */
+function ellipsize(s, cols) {
+  if (!(typeof cols === 'number' && cols > 0)) return '';
+  if (visibleWidth(s) <= cols) return s;
+  // One column is spent on the ellipsis, so the text gets cols-1. At cols === 1
+  // that leaves nothing, and the ellipsis alone is the honest answer.
+  const budget = cols - 1;
+  let out = '';
+  let w = 0;
+  for (const ch of s) {
+    const cw = charWidth(/** @type {number} */ (ch.codePointAt(0)));
+    if (w + cw > budget) break;
+    out += ch;
+    w += cw;
+  }
+  return out + '…';
+}
+
+module.exports = {
+  e, dim, bold, green, red, yellow, cyan, flash, pctColor, CRIT_PCT, usedLabel, bar, clampVisible, tok, fmtMins, fmtReset,
+  charWidth, visibleWidth, ellipsize,
+};

package/src/render/statusline.js

@@ -4,14 +4,47 @@
 // Plain text (no ANSI) so it renders cleanly wherever the status line appears.
 
 const { windowEstimate, binding } = require('../burn');
-const { fmtMins } = require('./shared');
+const { fmtMins, usedLabel, CRIT_PCT } = require('./shared');
+
+/**
+ * Deterministic middle ellipsis: the same input shortens the same way at
+ * every glance — the anti-marquee rule. (Animation was rejected outright:
+ * Claude re-renders this line per turn, not on a clock, so anything animated
+ * freezes exactly when the user is idle and orienting.)
+ * @param {string} s @param {number} max
+ */
+function midEllipsis(s, max) {
+  if (s.length <= max) return s;
+  const head = Math.ceil((max - 1) / 2);
+  const tail = max - 1 - head;
+  return s.slice(0, head) + '…' + (tail > 0 ? s.slice(-tail) : '');
+}
 
 /**
  * @param {any} view normalized economy data
- * @returns {string} one line, e.g. "Sonnet 4.6 · weekly · Sonnet ~5h · ctx 15% · $2.50"
+ * @param {{ name?: string|null, location?: string|null, cols?: number }} [identity]
+ *   The instance identity, shown FIRST so terminal end-truncation eats meters,
+ *   never orientation. The location half is LIVE (follows a mid-session cd)
+ *   and appears only when it differs from the name — "notes @ notes" says
+ *   nothing twice. `cols` bounds the identity: the location stays whole, the
+ *   name takes the ellipsis.
+ * @returns {string} one line, e.g. "a-is-awesome @ ccr · Opus 4.8 · 5h ~2h · ctx 15% · $2.50"
  */
-function renderStatusline(view) {
+function renderStatusline(view, identity = {}) {
   const parts = [];
+  const name = identity.name || null;
+  const loc = identity.location || null;
+  if (name) {
+    const withLoc = loc && loc !== name;
+    let shownName = name;
+    if (identity.cols && withLoc) {
+      const budget = identity.cols - (' @ '.length + (loc ? loc.length : 0));
+      if (name.length > budget) shownName = midEllipsis(name, Math.max(5, budget));
+    } else if (identity.cols && name.length > identity.cols) {
+      shownName = midEllipsis(name, Math.max(5, identity.cols));
+    }
+    parts.push(withLoc ? `${shownName} @ ${loc}` : shownName);
+  }
   if (view.model) parts.push(view.model);
 
   // Annotated because Array.isArray does not narrow an `any`: without this the
@@ -33,8 +66,20 @@ function renderStatusline(view) {
     const b = binding(live);
     if (b && b.minutesLeft != null) {
       const row = rows.find((r) => r.key === b.window);
-      const imminent = b.minutesLeft <= 30 ? '⚠ ' : '';
-      parts.push(`${imminent}${row ? row.label : b.window} ~${fmtMins(b.minutesLeft)}`);
+      const label = row ? row.label : b.window;
+      // Progressive disclosure: the one-line summary earns the precise used%
+      // ONLY in the critical zone, and truncated, so floor() still matches
+      // /usage. Below the zone the line stays a single glanceable beat — the
+      // time-to-limit already answers "am I near the wall?", and a percentage
+      // that is always present stops being a signal when it starts to matter.
+      const pct = row && row.est.usedPct >= CRIT_PCT ? ` ${usedLabel(row.est.usedPct)}%` : '';
+      if (b.minutesLeft <= 30) {
+        // "About to hit the wall" outranks orientation for the next thing the
+        // user types: the warning jumps ahead of everything, identity included.
+        parts.unshift(`⚠ ${label}${pct} ~${fmtMins(b.minutesLeft)}`);
+      } else {
+        parts.push(`${label}${pct} ~${fmtMins(b.minutesLeft)}`);
+      }
     } else {
       parts.push('within limits');
     }