glassbox-trace 0.11.0 → 0.12.0

package/src/memory.mjs

@@ -17,6 +17,7 @@ import { maskSecrets } from './fence.mjs';
 import { segments, actionRe, isShell, projectSessions } from './adhere.mjs';
 import { TEST_CMD, runFailed } from './claims.mjs';
 import { loadSessionFiles } from './cli.mjs';
+import { autoMemoryDir } from './memory-audit.mjs';
 const require = createRequire(import.meta.url);
 const core = require('./trace-core.js');
 
@@ -47,14 +48,25 @@ export const cleanCmd = (seg) => String(seg).replace(/^timeout\s+(?:-\S+\s+)*\d+
 
 // What a shell command does, in a word or two: the first segment that isn't navigation, its program and subcommand
 // ("npm test", "npm run e2e", "git push", "python -m pytest").
+// A word in a lesson key must look like a program or a subcommand, never like a password or a token: a key is
+// written into the agent's own memory (0.12 review: `echo <pw> | sudo -S apt-get …` became `Bash echo <pw>`).
+// Lowercase words joined by : . _ - are names (build:es2015, test:e2e2, build-v2, python3.11, webpack5); mixed case
+// with digits, or anything long, is not kept.
+const NAME_RE = /^[a-z][a-z0-9]*(?:[:._-][a-z0-9]+)*$/;
+const secretish = (w) => w.length > 40 || (!NAME_RE.test(w) && (w.length > 24 || (w.length >= 8 && /\d/.test(w) && /[A-Za-z]/.test(w)) || (/[A-Z]/.test(w) && /[a-z]/.test(w) && /\d/.test(w))));
 export function commandHead(cmd) {
-  const seg = cleanCmd(segments(cmd).find((s) => !/^(?:cd|pushd|popd|export|set|source|\.)(?:\s|$)/.test(s)) || '');
-  const toks = seg.split(/\s+/).filter(Boolean); if (!toks.length) return '';
+  // Not navigation, and not a segment that only feeds data to the next one (echo / printf / yes / cat <<).
+  const seg = cleanCmd(segments(cmd).find((s) => !/^(?:cd|pushd|popd|export|set|source|\.|echo|printf|yes|true|false|:)(?:\s|$)/.test(s) && !/^cat\s+<</.test(s)) || '');
+  let toks = seg.split(/\s+/).filter(Boolean);
+  while (toks.length && /^-/.test(toks[0])) toks = toks.slice(/^-[ugpCDhr]$/.test(toks[0]) ? 2 : 1); // what's left of `sudo -u bob …`
+  if (!toks.length) return '';
   const prog = toks[0].replace(/^.*[\\/]/, '');
-  if (/^python3?$/.test(prog) && toks[1] === '-m' && toks[2]) return `${prog} -m ${toks[2]}`;
+  if (!/^[\w.+-]+$/.test(prog) || secretish(prog)) return '';
+  if (/^python(?:3(?:\.\d+)?)?$/.test(prog) && toks[1] === '-m' && toks[2]) return `${prog} -m ${toks[2]}`;
   let i = 1; if (prog === 'git') while (i < toks.length && /^-/.test(toks[i])) i += /^-[Cc]$/.test(toks[i]) ? 2 : 1;
   let sub = toks[i] && /^[A-Za-z][\w:.-]*$/.test(toks[i]) ? toks[i] : toks[1] && /^--[a-z][\w-]*$/.test(toks[1]) ? toks[1] : '';
-  if (/^(?:run|exec|x|dlx)$/.test(sub) && toks[i + 1] && /^[\w:.-]+$/.test(toks[i + 1])) sub += ' ' + toks[i + 1];
+  if (sub && secretish(sub)) sub = '';
+  if (/^(?:run|exec|x|dlx)$/.test(sub) && toks[i + 1] && /^[\w:.-]+$/.test(toks[i + 1]) && !secretish(toks[i + 1])) sub += ' ' + toks[i + 1];
   return sub ? `${prog} ${sub}` : prog;
 }
 
@@ -298,25 +310,158 @@ export function forget(cwd, what) {
   return keys;
 }
 
-export function clearMemory(cwd) {
+export function clearMemory(cwd, opts = {}) {
   const removed = [];
   for (const f of [MEMORY_FILE, NOTES_FILE]) { const p = path.join(cwd, f); if (fs.existsSync(p)) { fs.unlinkSync(p); removed.push(p); } }
+  // The lessons block, wherever it was written (auto memory may have been switched on or off since).
+  for (const file of lessonsFiles(cwd, opts)) { if (writeLessonsBlock(file, null).changed) removed.push(`${file} (Glassbox lessons block)`); }
   return removed;
 }
 
+// ---------------------------------------------------------------------------------------------
+// One memory (0.12, DESIGN.md §21). The lessons the agent should act on go into the memory it already reads — the
+// auto memory MEMORY.md when auto memory is on and its folder exists, else <project>/CLAUDE.local.md; never the
+// shared CLAUDE.md — as one block Glassbox owns and rewrites at every Stop. The block is a projection of the ledger
+// (active lessons, worst first, the advice once per rule), so it can't drift from it; text outside the markers is
+// never touched. The end marker carries the keys, so the next session's first Stop knows what it was told.
+// ---------------------------------------------------------------------------------------------
+export const BLOCK_START = '<!-- glassbox:lessons:start';
+export const BLOCK_END = '<!-- glassbox:lessons:end';
+export const BLOCK_MAX = 1800;
+export function lessonsTarget(cwd, opts = {}) {
+  const am = autoMemoryDir({ project: cwd, home: opts.home, userHome: opts.userHome });
+  if (am.enabled && am.dir) return { file: path.join(am.dir, 'MEMORY.md'), kind: 'auto-memory' };
+  return { file: path.join(path.resolve(cwd), 'CLAUDE.local.md'), kind: 'local' };
+}
+function lessonsFiles(cwd, opts) {
+  const am = autoMemoryDir({ project: cwd, home: opts.home, userHome: opts.userHome });
+  return [am.dir ? path.join(am.dir, 'MEMORY.md') : null, path.join(path.resolve(cwd), 'CLAUDE.local.md')].filter((f) => f && fs.existsSync(f));
+}
+export function lessonsBlock(led, opts = {}) {
+  const o = Object.assign({}, MEMORY_DEFAULTS, opts), n = led.sessions.length;
+  let shown = lessonStats(led, o).filter((l) => l.active).slice(0, o.lessons);
+  const build = (list) => {
+    const advised = new Set();
+    const lines = list.map((l) => {
+      const adv = !advised.has(l.rule) && core.ADVICE[l.rule]; advised.add(l.rule);
+      const howOften = n === 1 ? 'in the only session so far' : `in ${l.sessions} of the last ${n} sessions`;
+      // No marker can be forged from a key, title or path: an HTML comment opener is broken with a zero-width non-joiner.
+      return '- ' + clip(`${maskSecrets(l.key)} — ${howOften}: ${maskSecrets(l.title)}.${adv ? ` Next time: ${adv}` : ''}`, 320).replace(/<!--/g, '<\u200c!--');
+    });
+    return [`${BLOCK_START} (rewritten by the Glassbox Stop hook from this project's transcripts; edit outside these markers; \`glassbox memory forget <lesson>\` drops one) -->`,
+      '## Glassbox: what keeps going wrong in this project', '', ...lines,
+      `${BLOCK_END} keys=${list.map((l) => encodeURIComponent(l.key)).join(',')} -->`, ''].join('\n');
+  };
+  if (!shown.length) return null;
+  let text = build(shown);
+  while (text.length > BLOCK_MAX && shown.length > 1) { shown = shown.slice(0, -1); text = build(shown); }
+  return { text, keys: shown.map((l) => l.key) };
+}
+export function blockKeys(text) {
+  const t = String(text || ''); const b = findBlocks(t.charCodeAt(0) === 0xfeff ? t.slice(1) : t).blocks[0];
+  return b ? b.keys.split(',').filter(Boolean).map((k) => { try { return decodeURIComponent(k); } catch (e) { return k; } }) : [];
+}
+// Put `body` (a block, or null to remove it) into the file. Markers count only as whole lines outside ``` / ~~~
+// fences, so a marker quoted in prose, inline code or a fenced example is never taken for the block (0.12 review);
+// a start line with no end line after it replaces only itself. In place when a block is there (any extra complete
+// blocks are dropped); under a leading `# ` title in an auto memory index, so it sits inside the 200-line cut; at the
+// end of anything else. Line endings and a BOM follow the file. Written through a symlink, with the file's mode, via
+// a temp file unique to this process; a file we can't write is left alone. Concurrent writers each start from the
+// whole file, so the last rename wins without losing the user's lines.
+const START_LINE = /^<!-- glassbox:lessons:start\b.*-->[ \t]*\r?$/;
+const END_LINE = /^<!-- glassbox:lessons:end keys=(\S*) -->[ \t]*\r?$/;
+// CommonMark fences: an opener is 3+ backticks or tildes (backtick openers can't have a backtick in the info
+// string); the closer is the same character, at least as long, with nothing after it. A fence still open at the end
+// of the file runs to the end in Markdown, but anything after it may be ours, so it is scanned again with that
+// opener read as text — otherwise every Stop would append another block inside it (0.12 review, round 2).
+function findBlocks(text, ignore = new Set()) {
+  const blocks = []; let fence = null, open = null, at = 0, idx = -1;
+  for (const line of text.split('\n')) {
+    idx++; const start = at, end = at + line.length + 1; at = end;
+    const l = line.replace(/\r$/, '');
+    if (fence) {
+      const c = l.match(/^[ \t]{0,3}(`{3,}|~{3,})[ \t]*$/);
+      if (c && c[1][0] === fence.ch && c[1].length >= fence.len) fence = null;
+      continue;
+    }
+    const o = l.match(/^[ \t]{0,3}(`{3,}|~{3,})(.*)$/);
+    if (o && !ignore.has(idx) && !(o[1][0] === '`' && o[2].includes('`'))) { fence = { ch: o[1][0], len: o[1].length, idx }; continue; }
+    if (START_LINE.test(line)) { if (!open) open = { start, lineEnd: Math.min(end, text.length) }; continue; }
+    const m = line.match(END_LINE);
+    if (m && open) { blocks.push({ start: open.start, end: Math.min(end, text.length), keys: m[1] }); open = null; }
+  }
+  if (fence) return findBlocks(text, new Set([...ignore, fence.idx])); // each pass ignores one more opener: it ends
+  return { blocks, broken: open };
+}
+export function writeLessonsBlock(file, body, kind) {
+  let real = file;
+  try { real = fs.realpathSync(file); } catch (e) { let link = false; try { link = fs.lstatSync(file).isSymbolicLink(); } catch (e2) { } if (link) return { file, changed: false, reason: 'a link to nothing' }; }
+  const exists = fs.existsSync(real);
+  // Read-only by its mode bits (root passes an access() check on a 0444 file) or by access(): someone froze it; leave it.
+  if (exists) { let ok = (fs.statSync(real).mode & 0o222) !== 0; try { fs.accessSync(real, fs.constants.W_OK); } catch (e) { ok = false; } if (!ok) return { file, changed: false, reason: 'not writable' }; }
+  const raw = exists ? fs.readFileSync(real, 'utf8') : '';
+  const bom = raw.charCodeAt(0) === 0xfeff ? '' : '';
+  const text = bom ? raw.slice(1) : raw;
+  const eol = /\r\n/.test(text) ? '\r\n' : '\n';
+  const blk = body ? body.replace(/\r?\n/g, eol) : '';
+  const { blocks, broken } = findBlocks(text);
+  let out;
+  if (blocks.length) {
+    out = ''; let pos = 0;
+    blocks.forEach((b, i) => { out += text.slice(pos, b.start) + (i === 0 ? blk : ''); pos = b.end; });
+    let rest = text.slice(pos);
+    // Removed: take back the blank line that was put beside it, so the file reads as it did before the block.
+    if (!blk && rest.startsWith(eol) && (out === '' || out.endsWith(eol + eol))) rest = rest.slice(eol.length);
+    else if (!blk && rest === '' && out.endsWith(eol + eol)) out = out.slice(0, -eol.length);
+    out += rest;
+  } else if (broken) out = text.slice(0, broken.start) + blk + text.slice(broken.lineEnd);
+  else if (!blk) return { file, changed: false };
+  else if (kind === 'auto-memory') {
+    const m = /^# [^\r\n]*\r?\n(?:\r?\n)?/.exec(text); const at = m ? m[0].length : 0;
+    out = text.slice(0, at) + blk + (text.slice(at) ? eol : '') + text.slice(at);
+  } else out = text + (text && !text.endsWith('\n') ? eol : '') + (text.trim() ? eol : '') + blk;
+  out = bom + out;
+  if (out === raw) return { file, changed: false };
+  if (!exists && !out) return { file, changed: false };
+  fs.mkdirSync(path.dirname(real), { recursive: true });
+  const mode = exists ? fs.statSync(real).mode & 0o777 : 0o644;
+  const tmp = `${real}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}.glassbox~`;
+  try { fs.writeFileSync(tmp, out, { flag: 'wx', mode }); fs.chmodSync(tmp, mode); fs.renameSync(tmp, real); }
+  catch (e) { try { fs.unlinkSync(tmp); } catch (e2) { } throw e; }
+  return { file, changed: true };
+}
+// The Stop hook's part: what this session started with (first Stop only), then the block for the next one.
+export function syncLessonsBlock(cwd, opts = {}) {
+  if (!memoryPath(cwd)) return null;
+  const t = lessonsTarget(cwd, opts);
+  const led = loadLedger(cwd);
+  const blk = lessonsBlock(led, opts);
+  return Object.assign(writeLessonsBlock(t.file, blk ? blk.text : null, t.kind), { kind: t.kind, keys: blk ? blk.keys : [] });
+}
+export function toldFromBlock(cwd, sessionId, opts = {}) {
+  if (!sessionId || !memoryPath(cwd)) return false;
+  const led = loadLedger(cwd);
+  if (led.sessions.some((x) => x.id === sessionId) || led.pending[sessionId]) return false;
+  const t = lessonsTarget(cwd, opts);
+  const keys = fs.existsSync(t.file) ? blockKeys(fs.readFileSync(t.file, 'utf8')) : [];
+  return noteTold(cwd, sessionId, keys);
+}
+
 // ---------------------------------------------------------------------------------------------
 // glassbox memory: the note the next session will get, and the lessons behind it.
 // ---------------------------------------------------------------------------------------------
 export function memoryReport(opts = {}) {
   const project = path.resolve(opts.project || process.cwd());
   const led = loadLedger(project), o = Object.assign({}, MEMORY_DEFAULTS, opts);
+  const target = lessonsTarget(project, opts); const blk = lessonsBlock(led, o);
   const lessons = lessonStats(led, o);
   const note = memoryNote(project, Object.assign({}, o, { ledger: led }));
   const told = lessons.reduce((s, l) => s + l.told, 0), recurred = lessons.reduce((s, l) => s + l.recurred, 0);
   return { glassbox: core.VERSION, kind: 'memory', schema: 1, project, file: fs.existsSync(path.join(project, MEMORY_FILE)) ? path.join(project, MEMORY_FILE) : null, updated: led.updated,
     sessions: led.sessions.length, window: o.window, retireAfter: o.retireAfter,
     summary: { lessons: lessons.length, active: lessons.filter((l) => l.active).length, retired: lessons.filter((l) => !l.active).length, told, recurred },
-    lessons, recent: led.sessions.slice().reverse().slice(0, o.recent).map((d) => ({ id: d.id, start: d.start, line: digestLine(d) })), note: note ? note.text : null };
+    lessons, recent: led.sessions.slice().reverse().slice(0, o.recent).map((d) => ({ id: d.id, start: d.start, line: digestLine(d) })), note: note ? note.text : null,
+    block: { file: target.file, kind: target.kind, text: blk ? blk.text : null } };
 }
 export function memoryText(rep) {
   const s = rep.summary;
@@ -327,6 +472,11 @@ export function memoryText(rep) {
     L.push('');
     for (const l of rep.lessons) L.push(`  ${(l.active ? 'ACTIVE' : 'RETIRED').padEnd(8)} ${l.key}  ·  ${l.sessions} session${l.sessions === 1 ? '' : 's'}, last ${String(l.lastSeen || '').slice(0, 10)}${l.told ? ` · told ${l.told}, came back ${l.recurred}` : ''}${l.quiet ? ` · quiet ${l.quiet}` : ''}`);
   }
+  if (rep.block) {
+    L.push('', rep.block.text ? `  The agent's own memory carries these lessons, in ${rep.block.file} (${rep.block.kind === 'auto-memory' ? 'auto memory' : 'CLAUDE.local.md'}):` : `  No lessons to carry: the block in ${rep.block.file} is removed at the next Stop.`);
+    if (rep.block.text) { L.push(''); for (const line of rep.block.text.replace(/\n$/, '').split('\n')) L.push('  │ ' + line); }
+    L.push('', '  (With --memory glassbox the next session gets this note from the SessionStart hook instead:)');
+  }
   L.push('', rep.note ? '  The next session in this project starts with this note:' : '  The next session in this project starts with no note.');
   if (rep.note) { L.push(''); for (const line of rep.note.replace(/\n$/, '').split('\n')) L.push('  │ ' + line); }
   L.push('', '  glassbox memory forget <key|rule> drops a lesson · glassbox memory clear deletes the memory · glassbox recall <words> searches it');
@@ -371,7 +521,8 @@ export function recall(opts = {}) {
   for (const s of list) {
     const files = loadSessionFiles(s);
     const words = terms.flatMap((t) => t.split(/\s+/)).filter(rawSafe);
-    if (words.length) { const raw = files.map((f) => f.text).join('\n').toLowerCase(); if (!words.every((w) => raw.includes(w))) continue; }
+    // The raw-text shortcut needs the text; a streamed (big) transcript has records instead and is parsed (0.12).
+    if (words.length && files.every((f) => typeof f.text === 'string')) { const raw = files.map((f) => f.text).join('\n').toLowerCase(); if (!words.every((w) => raw.includes(w))) continue; }
     const d = digestOf(core.parseTrace(files), { cwd: project, id: s.id }); parsed++;
     const prev = byId.get(s.id);
     byId.set(s.id, Object.assign(d, { hit: prev ? prev.hit : [], cost: prev ? prev.cost : null, source: prev ? 'both' : 'transcript' }));

package/src/plan.mjs

@@ -0,0 +1,253 @@
+// glassbox plan — what a Pro/Max plan is buying, from the transcripts on this machine.
+//
+// Glassbox prices every request at API list price. A plan subscriber doesn't pay that; what they want to know is
+// what the plan carried and where the heavy stretches were. `plan` reads the plan tier from ~/.claude.json (two
+// fields, nothing else), buckets every request by its own timestamp into billing months, the last 7 days and
+// rebuilt 5-hour windows, and finds limit hits. It cannot see the plan's limits: Claude Code gives the % used only
+// to the status line, never to a transcript, and the limits count claude.ai and other machines too (DESIGN.md §22).
+// Nothing leaves the machine.
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { findSessions, loadSessionFiles, sessionTitle, claudeHome } from './cli.mjs';
+import { readTextFile } from './textfile.mjs';
+import { readSnapshots } from './statusline.mjs';
+const require = createRequire(import.meta.url);
+const core = require('./trace-core.js');
+
+const H = 3600e3, D = 24 * H, WINDOW = 5 * H;
+
+// Rate-limit tiers as ~/.claude.json names them → plan and its monthly price in USD (claude.com/pricing).
+export const PLANS = {
+  pro: { label: 'Pro', price: 20 },
+  max_5x: { label: 'Max 5x', price: 100 },
+  max_20x: { label: 'Max 20x', price: 200 },
+};
+export const tierPlan = (tier) => { const m = String(tier || '').toLowerCase().match(/(max_20x|max_5x|pro)\b/); return m ? m[1] : null; };
+
+// Where Claude Code keeps .claude.json: inside the home when the home is a CLAUDE_CONFIG_DIR, else next to it.
+// The first one that has a signed-in account wins (an old copy without one can sit inside ~/.claude).
+export function readPlan(home) {
+  home = home || claudeHome();
+  let first = null;
+  for (const f of [path.join(home, '.claude.json'), path.join(path.dirname(home), '.claude.json')]) {
+    if (!fs.existsSync(f)) continue;
+    first = first || f;
+    let acct; try { acct = (JSON.parse(readTextFile(f)) || {}).oauthAccount; } catch (e) { continue; }
+    if (!acct) continue;
+    const tier = typeof acct.organizationRateLimitTier === 'string' ? acct.organizationRateLimitTier : typeof acct.userRateLimitTier === 'string' ? acct.userRateLimitTier : null;
+    return { file: f, plan: tierPlan(tier), tier, since: acct.subscriptionCreatedAt || null };
+  }
+  return { file: first, plan: null };
+}
+
+// Billing months run from the subscription's day and time of day (UTC); a 31st falls on a short month's last day.
+const monthStart = (y, m, day, tod) => { const last = new Date(Date.UTC(y, m + 1, 0)).getUTCDate(); return Date.UTC(y, m, Math.min(day, last)) + tod; };
+export function billingPeriods(anchor, now, count = 2) {
+  const a = new Date(anchor), day = a.getUTCDate(), tod = anchor - Date.UTC(a.getUTCFullYear(), a.getUTCMonth(), a.getUTCDate());
+  const n = new Date(now); let y = n.getUTCFullYear(), m = n.getUTCMonth();
+  if (monthStart(y, m, day, tod) > now) m--;
+  const out = [];
+  for (let i = 0; i < count; i++) { const from = monthStart(y, m - i, day, tod), to = monthStart(y, m - i + 1, day, tod); if (to <= anchor) break; out.push({ from: Math.max(from, anchor), to }); }
+  return out;
+}
+
+// A 5-hour window opens at the first request after the previous one closed (the way ccusage `blocks` rebuilds them).
+// Usage from claude.ai or another machine can open a window Glassbox never sees, so these are estimates.
+export function rebuildWindows(reqs) {
+  const out = [];
+  for (const r of reqs) { const w = out[out.length - 1]; if (!w || r.t >= w.start + WINDOW) out.push({ start: r.t, end: r.t + WINDOW, reqs: [r] }); else w.reqs.push(r); }
+  return out;
+}
+
+// A limit hit is the synthetic assistant record Claude Code writes in place of a reply.
+const LIMIT_TEXT = /usage limit|hit your limit|limit reached|limit will reset|resets? (?:at|in)\b/i;
+export function limitKind(r) {
+  if (!r.isApiError) return null;
+  const text = r.blocks.filter((b) => b.type === 'text').map((b) => b.text).join(' ');
+  if (LIMIT_TEXT.test(text) || r.apiError === 'billing_error') return 'plan';
+  if (r.apiError === 'rate_limit') return 'rate';
+  return null;
+}
+
+const family = (m) => String(m || 'unknown').replace(/-\d{8}$/, '');
+function bucket(reqs, from, to) {
+  const list = reqs.filter((r) => r.t >= from && r.t < to);
+  const byModel = {}, bySession = {};
+  for (const r of list) { byModel[family(r.model)] = (byModel[family(r.model)] || 0) + r.cost; bySession[r.session] = (bySession[r.session] || 0) + r.cost; }
+  const list$ = list.reduce((a, r) => a + r.cost, 0);
+  return { list: list$, requests: list.length, byModel, bySession };
+}
+
+export function plan(opts = {}) {
+  const home = opts.home || claudeHome();
+  const now = opts.now != null ? opts.now : Date.now();
+  const since = opts.since != null ? opts.since : 7 * D;
+  const found = readPlan(home);
+  const key = opts.plan !== undefined ? (opts.plan === 'none' ? null : tierPlan(String(opts.plan).replace(/-/g, '_'))) : found.plan;
+  if (opts.plan !== undefined && opts.plan !== 'none' && !key) throw new Error(`--plan must be pro, max-5x, max-20x or none (got "${opts.plan}")`);
+  const info = key ? PLANS[key] : null;
+  const price = opts.planPrice != null ? opts.planPrice : info ? info.price : null;
+
+  // The billing anchor: --bill-day (00:00 UTC on that day), else the subscription's own start.
+  // A January a year back carries any day 1–31, and billingPeriods only reads its day and time of day.
+  let anchor = null;
+  if (opts.billDay != null) {
+    if (!Number.isInteger(opts.billDay) || opts.billDay < 1 || opts.billDay > 31) throw new Error(`--bill-day must be a day of the month, 1–31 (got "${opts.billDay}")`);
+    anchor = Date.UTC(new Date(now).getUTCFullYear() - 1, 0, opts.billDay);
+  } else if (found.since && key) anchor = Date.parse(found.since);
+  const periods = info && anchor != null && Number.isFinite(anchor) ? billingPeriods(anchor, now, 2) : [];
+  const from = Math.min(now - since, now - 7 * D, ...periods.map((p) => p.from));
+
+  // Every request, once: a resumed session repeats earlier records under the same requestId.
+  const seen = new Set(), reqs = [], hits = [], files = {}; const unpriced = new Set(); let unpricedN = 0, sessions = 0;
+  for (const s of findSessions({ home }).filter((x) => x.mtime >= from)) {
+    let trace; try { trace = core.parseTrace(loadSessionFiles(s)); } catch (e) { continue; }
+    sessions++; files[s.id] = s.file;
+    for (const r of trace.requests) {
+      if (r.start == null || r.start < from || seen.has(r.id)) continue;
+      seen.add(r.id);
+      const kind = limitKind(r);
+      if (kind) { if (r.start >= now - since) hits.push({ t: r.start, kind, session: s.id, code: r.apiError || null }); continue; }
+      if (r.isApiError || r.model === '<synthetic>') continue; // written by Claude Code, not an API reply
+      const cost = core.requestCost(r.usage, core.rateFor(r.model, opts.rates));
+      if (cost == null) { unpricedN++; if (r.model) unpriced.add(r.model); continue; }
+      reqs.push({ t: r.start, cost, model: r.model, session: s.id });
+    }
+  }
+  reqs.sort((a, b) => a.t - b.t); hits.sort((a, b) => a.t - b.t);
+
+  const title = (id) => { if (opts.redact) return null; const t = sessionTitle(files[id]); return /^\((no prompt found|unreadable)\)$/.test(t) ? null : t; };
+  const topOf = (bySession, total) => { const e = Object.entries(bySession).sort((a, b) => b[1] - a[1])[0]; return e ? { session: e[0], list: e[1], share: total ? e[1] / total : 0, title: title(e[0]) } : null; };
+  const models = (byModel, total) => Object.entries(byModel).sort((a, b) => b[1] - a[1]).map(([model, list]) => ({ model, list, share: total ? list / total : 0 }));
+
+  // Rebuilt from everything read (so the first window in range isn't cut at its edge), kept if it ends in range.
+  const windows = key ? rebuildWindows(reqs).filter((w) => w.end > now - since).map((w) => {
+    const b = bucket(w.reqs, w.start, w.end);
+    return { start: w.start, end: w.end, open: now < w.end, list: b.list, requests: b.requests, top: topOf(b.bySession, b.list) };
+  }) : [];
+  const week = bucket(reqs, now - 7 * D, now + 1);
+  const rateCard = core.rateCardCheck(reqs.map((r) => r.model).concat([...unpriced]), opts.rates || undefined, { latest: reqs.length ? reqs[reqs.length - 1].t : null, custom: !!(opts.rates && opts.rates._custom) });
+  const live = opts.live ? liveFrom(opts.snapshots || readSnapshots(home), reqs, { now, since, title, top: opts.top || 5 }) : null;
+  return {
+    glassbox: core.VERSION, schema: 1, kind: 'plan', generated: now, redacted: !!opts.redact,
+    scope: 'Claude Code transcripts on this machine; claude.ai, the apps and other machines are not included',
+    plan: { key, label: info ? info.label : null, price, priceFrom: opts.planPrice != null ? 'flag' : info ? 'default' : null, tier: found.tier || null, file: found.file, override: opts.plan !== undefined },
+    sessions, requests: reqs.length, since,
+    periods: periods.map((p) => { const b = bucket(reqs, p.from, p.to); const elapsed = Math.min(now, p.to) - p.from;
+      return { from: p.from, to: p.to, current: now < p.to, days: Math.round((p.to - p.from) / D), daysElapsed: Math.max(1, Math.ceil(elapsed / D)), list: b.list, requests: b.requests, multiple: price ? b.list / price : null, models: models(b.byModel, b.list) }; }),
+    last7d: { from: now - 7 * D, list: week.list, requests: week.requests, models: models(week.byModel, week.list) },
+    windows: { count: windows.length, current: windows.find((w) => w.open) || null, top: windows.slice().sort((a, b) => b.list - a.list).slice(0, opts.top || 5) },
+    limitHits: hits,
+    unpriced: { requests: unpricedN, models: [...unpriced] },
+    rateCard, live, pricing: core.pricingNote(reqs.map((r) => r.model), opts.rates || undefined),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// --live: the status line's snapshots (src/statusline.mjs) against the local requests
+// ---------------------------------------------------------------------------
+// A window is known exactly from its resets_at: the 5-hour one started 5 h before it, the week 7 days before.
+// resets_at is whole seconds and can wobble by one between readings, so readings are grouped to the minute.
+// A session's share is what the % did between its own first and last reading in each window: other sessions,
+// claude.ai and other machines in that time count too, so it is "while it ran", not "because of it".
+export function liveFrom(snaps, reqs, opts) {
+  const { now, since } = opts;
+  const recent = snaps.filter((s) => s.t >= now - Math.max(since, 7 * D));
+  const groups = (kind, len) => {
+    const by = new Map();
+    for (const s of recent) { const w = s[kind]; if (!w) continue; const k = Math.round(w.resets / 60e3); const g = by.get(k) || { start: w.resets - len, end: w.resets, peak: 0, readings: 0, first: s.t, last: s.t }; g.peak = Math.max(g.peak, w.pct); g.readings++; g.last = s.t; by.set(k, g); }
+    return [...by.values()].sort((a, b) => b.start - a.start).map((g) => { const b = bucket(reqs, g.start, Math.min(g.end, now)); return Object.assign(g, { open: now < g.end, list: b.list, requests: b.requests }); });
+  };
+  const deltas = (list, kind) => { const by = new Map(); for (const s of list) { const w = s[kind]; if (!w) continue; const k = Math.round(w.resets / 60e3); const g = by.get(k) || { lo: w.pct, hi: w.pct }; g.hi = w.pct; by.set(k, g); } let d = 0; for (const g of by.values()) d += Math.max(0, g.hi - g.lo); return d; };
+  const bySession = new Map(); for (const s of recent) { if (!s.session) continue; if (!bySession.has(s.session)) bySession.set(s.session, []); bySession.get(s.session).push(s); }
+  const sessions = [...bySession.entries()].filter(([, l]) => l.length >= 2).map(([id, l]) => {
+    const from = l[0].t, to = l[l.length - 1].t, b = bucket(reqs.filter((r) => r.session === id), from, to + 1);
+    return { session: id, title: opts.title(id), readings: l.length, from, to, week: deltas(l, 'week'), five: deltas(l, 'five'), list: b.list, requests: b.requests };
+  }).sort((a, b) => b.week - a.week || b.five - a.five).slice(0, opts.top);
+  const latest = recent[recent.length - 1] || null;
+  const fresh = (w) => w && w.resets > now ? w : null;
+  return {
+    snapshots: recent.length, newest: latest ? latest.t : null,
+    now: latest ? { t: latest.t, five: fresh(latest.five), week: fresh(latest.week) } : null,
+    fiveHour: groups('five', 5 * H).slice(0, opts.top), weeks: groups('week', 7 * D).slice(0, 2), sessions,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Rendering
+// ---------------------------------------------------------------------------
+const DAYS = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'], MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+const p2 = (n) => String(n).padStart(2, '0');
+const day = (t) => { const d = new Date(t); return `${DAYS[d.getDay()]} ${d.getDate()} ${MONTHS[d.getMonth()]}`; };
+const hm = (t) => { const d = new Date(t); return `${p2(d.getHours())}:${p2(d.getMinutes())}`; };
+const usd = (v) => '$' + v.toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 });
+const pct = (v) => v > 0 && v < 0.005 ? '<1%' : Math.round(v * 100) + '%';
+const mult = (v) => v.toFixed(1) + '×';
+const short = (m) => m.replace(/^claude-/, '').replace(/-(\d+)-(\d+)$/, ' $1.$2').replace(/-(\d+)$/, ' $1').replace(/^./, (c) => c.toUpperCase());
+const modelLine = (ms) => ms.slice(0, 3).map((m) => `${short(m.model)} ${pct(m.share)}`).join(' · ');
+const sinceText = (ms) => ms % D === 0 ? `${ms / D}d` : ms % H === 0 ? `${ms / H}h` : `${Math.round(ms / 60e3)}m`;
+const NOTE = ['List price is what the same tokens would cost on the API. It isn\'t money saved, and it isn\'t your share',
+  'of the plan\'s limits: Claude Code shows those only to the status line, and they count claude.ai and other machines too.'];
+
+function headline(rep) {
+  const p = rep.plan;
+  if (!p.key) return `Glassbox plan · no Claude plan found${p.file ? ` in ${p.file}` : ''} (API key, Bedrock or Vertex?) · list price is what you pay`;
+  return `Glassbox plan · ${p.label}${p.override ? '' : ' (from .claude.json)'} · ${p.price != null ? usd(p.price).replace(/\.00$/, '') + '/month' + (p.priceFrom === 'default' ? ' (USD list; --plan-price for yours)' : '') : 'no price'} · Claude Code on this machine only`;
+}
+const periodLabel = (p) => p.current ? `billing month from ${day(p.from)}` : `${day(p.from)} – ${day(p.to)}`;
+const windowRow = (w, redact) => `${day(w.start)} ${hm(w.start)}–${hm(w.end)}  ${usd(w.list).padStart(10)}  ${String(w.requests).padStart(5)} req${w.top ? `  top ${w.top.session.slice(0, 8)} ${pct(w.top.share)}${!redact && w.top.title ? ` "${w.top.title.slice(0, 50)}"` : ''}` : ''}`;
+
+export function planText(rep) {
+  const L = [headline(rep), ''];
+  for (const p of rep.periods) L.push(`  ${periodLabel(p).padEnd(32)} ${usd(p.list).padStart(11)} list${p.multiple != null ? `   vs ${usd(rep.plan.price).replace(/\.00$/, '')} plan   ${mult(p.multiple)}` : ''}${p.current ? `   (day ${p.daysElapsed} of ${p.days})` : ''}`);
+  L.push(`  ${'last 7 days'.padEnd(32)} ${usd(rep.last7d.list).padStart(11)} list   ${modelLine(rep.last7d.models)}`);
+  if (rep.plan.key) {
+    L.push('', `  5-hour windows, last ${sinceText(rep.since)}: ${rep.windows.count} (rebuilt from request times; usage elsewhere can shift them)`);
+    if (rep.windows.current) L.push(`    now   ${windowRow(rep.windows.current, rep.redacted)}`);
+    for (const w of rep.windows.top) if (!rep.windows.current || w.start !== rep.windows.current.start) L.push(`          ${windowRow(w, rep.redacted)}`);
+    L.push('', rep.limitHits.length ? `  limit hits: ${rep.limitHits.length}` : `  limit hits: none in the last ${sinceText(rep.since)}`);
+    for (const h of rep.limitHits.slice(-10)) L.push(`    ${day(h.t)} ${hm(h.t)}  ${h.kind === 'plan' ? 'plan limit' : 'rate limited'}  ${h.session.slice(0, 8)}`);
+  }
+  if (rep.live) L.push('', ...liveLines(rep.live, rep.redacted, rep.generated).map((s) => '  ' + s));
+  if (rep.unpriced.requests) L.push('', `  ${rep.unpriced.requests} request${rep.unpriced.requests === 1 ? '' : 's'} not priced (no rate for ${rep.unpriced.models.join(', ') || 'an unnamed model'}; --rates FILE adds one)`);
+  if (rep.pricing) L.push('', '  ' + rep.pricing);
+  const rl = core.rateCardLine(rep.rateCard); if (rl) L.push('', '  ' + rl);
+  L.push('', ...(rep.live && rep.live.snapshots ? NOTE_LIVE : NOTE).map((s) => '  ' + s));
+  return L.join('\n');
+}
+
+const NOTE_LIVE = ['List price is what the same tokens would cost on the API, not money saved. The % readings are the plan\'s own,',
+  'from the status line; they count claude.ai and other machines too, which the local list price does not.'];
+const ago = (ms) => ms < 60e3 ? 'just now' : ms < H ? `${Math.round(ms / 60e3)}m ago` : ms < D ? `${Math.round(ms / H)}h ago` : `${Math.round(ms / D)}d ago`;
+const span = (a, b) => `${day(a)} ${hm(a)} – ${day(b)} ${hm(b)}`;
+function liveLines(lv, redact, now) {
+  if (!lv.snapshots) return ['From the status line: no readings yet. Run `glassbox statusline install`, then use Claude Code for a while.'];
+  const L = [`From the status line: ${lv.snapshots} reading${lv.snapshots === 1 ? '' : 's'}, newest ${ago(now - lv.newest)}`];
+  const n = lv.now;
+  L.push(`  latest   ${n.five ? `5h ${pct(n.five.pct / 100)} (resets ${hm(n.five.resets)})` : '5h — (reset since)'} · ${n.week ? `week ${pct(n.week.pct / 100)} (resets ${day(n.week.resets)} ${hm(n.week.resets)})` : 'week — (reset since)'}`);
+  if (lv.fiveHour.length) { L.push('  5-hour windows (exact)'); for (const w of lv.fiveHour) L.push(`    ${day(w.start)} ${hm(w.start)}–${hm(w.end)}  peak ${pct(w.peak / 100).padStart(4)}  ${usd(w.list).padStart(10)} local${w.open ? '  (open)' : ''}`); }
+  if (lv.weeks.length) { L.push('  weeks'); for (const w of lv.weeks) L.push(`    ${span(w.start, w.end)}  peak ${pct(w.peak / 100).padStart(4)}  ${usd(w.list).padStart(10)} local${w.open ? '  (open)' : ''}`); }
+  if (lv.sessions.length) {
+    L.push('  sessions, by how much the week moved while each ran (other usage in that time counts too)');
+    for (const s of lv.sessions) L.push(`    ${s.session.slice(0, 8)}  week +${pct(s.week / 100)}  5h +${pct(s.five / 100)}  ${usd(s.list).padStart(9)} local${!redact && s.title ? `  "${s.title.slice(0, 50)}"` : ''}`);
+  }
+  return L;
+}
+
+export function planMarkdown(rep) {
+  const L = [`## ${headline(rep)}`, '', '| Period | List price | Plan | Multiple | Top models |', '|---|---:|---:|---:|---|'];
+  for (const p of rep.periods) L.push(`| ${periodLabel(p)}${p.current ? ` (day ${p.daysElapsed} of ${p.days})` : ''} | ${usd(p.list)} | ${rep.plan.price != null ? usd(rep.plan.price) : '—'} | ${p.multiple != null ? mult(p.multiple) : '—'} | ${modelLine(p.models)} |`);
+  L.push(`| last 7 days | ${usd(rep.last7d.list)} | | | ${modelLine(rep.last7d.models)} |`);
+  if (rep.plan.key) {
+    L.push('', `### 5-hour windows, last ${sinceText(rep.since)}: ${rep.windows.count}`, '', '*Rebuilt from request times; usage elsewhere can shift them.*', '', '| Window | List price | Requests | Top session |', '|---|---:|---:|---|');
+    const rows = rep.windows.current ? [rep.windows.current, ...rep.windows.top.filter((w) => w.start !== rep.windows.current.start)] : rep.windows.top;
+    for (const w of rows) L.push(`| ${w.open ? 'now: ' : ''}${day(w.start)} ${hm(w.start)}–${hm(w.end)} | ${usd(w.list)} | ${w.requests} | ${w.top ? `\`${w.top.session.slice(0, 8)}\` ${pct(w.top.share)}${!rep.redacted && w.top.title ? ` ${w.top.title.slice(0, 50).replace(/\|/g, '\\|')}` : ''}` : ''} |`);
+    L.push('', `**Limit hits:** ${rep.limitHits.length ? rep.limitHits.map((h) => `${day(h.t)} ${hm(h.t)} (${h.kind === 'plan' ? 'plan limit' : 'rate limited'}, \`${h.session.slice(0, 8)}\`)`).join(', ') : `none in the last ${sinceText(rep.since)}`}`);
+  }
+  if (rep.live) L.push('', '### Live', '', '```', ...liveLines(rep.live, rep.redacted, rep.generated), '```');
+  if (rep.unpriced.requests) L.push('', `${rep.unpriced.requests} request(s) not priced: no rate for ${rep.unpriced.models.join(', ') || 'an unnamed model'}.`);
+  const rl = core.rateCardLine(rep.rateCard); if (rl) L.push('', `> ${rl}`);
+  L.push('', (rep.live && rep.live.snapshots ? NOTE_LIVE : NOTE).join(' '), '');
+  return L.join('\n');
+}

package/src/statusline.mjs

@@ -0,0 +1,154 @@
+// glassbox statusline — the plan's real limits in Claude Code's status bar, and a log of them for `plan --live`.
+//
+// Claude Code gives a status-line command what it never writes to a transcript: `rate_limits.five_hour` and
+// `rate_limits.seven_day`, each { used_percentage 0–100, resets_at epoch seconds }, for subscribers, after the first
+// API response. This prints them in one line and appends a snapshot to <claude home>/glassbox/limits.jsonl when
+// they change, so `plan --live` can show exact windows and what each session took (DESIGN.md §23). It runs on
+// every status refresh, so it parses no transcript and never fails loudly: whatever goes wrong, it prints a line
+// and exits 0. Nothing leaves the machine.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { claudeHome, settingsPath } from './cli.mjs';
+import { readTextFile } from './textfile.mjs';
+
+const M = 60e3, H = 60 * M;
+export const LIMITS_CAP = 4 * 1024 * 1024; // then limits.jsonl becomes limits.1.jsonl (one older file kept)
+const REPEAT_MS = 10 * M;                  // an unchanged reading is logged again after this long
+export const limitsFile = (home) => path.join(home || claudeHome(), 'glassbox', 'limits.jsonl');
+export const previousFile = (home) => path.join(home || claudeHome(), 'glassbox', 'statusline-previous.json');
+
+// ---------------------------------------------------------------------------
+// Snapshots
+// ---------------------------------------------------------------------------
+const toMs = (v) => typeof v === 'number' ? (v < 1e12 ? v * 1000 : v) : typeof v === 'string' ? Date.parse(v) : NaN;
+const win = (w) => w && typeof w.used_percentage === 'number' && Number.isFinite(toMs(w.resets_at)) ? { pct: w.used_percentage, resets: toMs(w.resets_at) } : null;
+
+export function snapshotFrom(input, now = Date.now()) {
+  const rl = input && input.rate_limits;
+  if (!rl) return null;
+  const five = win(rl.five_hour), week = win(rl.seven_day);
+  if (!five && !week) return null;
+  return { t: now, session: input.session_id || null, model: (input.model && input.model.id) || null, five, week };
+}
+
+const same = (a, b) => (!a && !b) || (a && b && a.pct === b.pct && a.resets === b.resets);
+// The last few KB of the log, parsed newest first (a partial first line is skipped).
+function tail(file, bytes = 65536) {
+  let fd; try { fd = fs.openSync(file, 'r'); const size = fs.fstatSync(fd).size; const n = Math.min(size, bytes); const buf = Buffer.alloc(n); fs.readSync(fd, buf, 0, n, size - n);
+    const lines = buf.toString('utf8').split('\n'); if (n < size) lines.shift();
+    const out = []; for (let i = lines.length - 1; i >= 0; i--) { if (!lines[i].trim()) continue; try { out.push(JSON.parse(lines[i])); } catch (e) { } } return out;
+  } catch (e) { return []; } finally { if (fd != null) fs.closeSync(fd); }
+}
+
+// Append when this session's reading changed, or REPEAT_MS after its last line. Returns whether it wrote.
+export function logSnapshot(home, snap) {
+  if (!snap) return false;
+  const file = limitsFile(home);
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const last = tail(file).find((s) => s.session === snap.session);
+  if (last && same(last.five, snap.five) && same(last.week, snap.week) && snap.t - last.t < REPEAT_MS) return false;
+  try { if (fs.statSync(file).size > LIMITS_CAP) fs.renameSync(file, file.replace(/\.jsonl$/, '.1.jsonl')); } catch (e) { }
+  fs.appendFileSync(file, JSON.stringify(snap) + '\n', { mode: 0o600 });
+  return true;
+}
+
+export function readSnapshots(home) {
+  const file = limitsFile(home), out = [];
+  for (const f of [file.replace(/\.jsonl$/, '.1.jsonl'), file]) {
+    if (!fs.existsSync(f)) continue;
+    for (const line of fs.readFileSync(f, 'utf8').split('\n')) { if (!line.trim()) continue; try { const s = JSON.parse(line); if (typeof s.t === 'number') out.push(s); } catch (e) { } }
+  }
+  return out.sort((a, b) => a.t - b.t);
+}
+
+// ---------------------------------------------------------------------------
+// The line
+// ---------------------------------------------------------------------------
+const DAYS = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
+const p2 = (n) => String(n).padStart(2, '0');
+const hm = (t) => { const d = new Date(t); return `${p2(d.getHours())}:${p2(d.getMinutes())}`; };
+const left = (ms) => { const m = Math.max(0, Math.round(ms / M)); return m >= 60 ? `${Math.floor(m / 60)}h${p2(m % 60)}m` : `${m}m`; };
+const pctText = (v) => (Math.round(v * 10) / 10) + '%';
+
+export function statusText(input, opts = {}) {
+  const now = opts.now != null ? opts.now : Date.now();
+  const color = opts.color !== false;
+  const paint = (pct, s) => !color ? s : `\x1b[${pct >= 80 ? 31 : pct >= 50 ? 33 : 32}m${s}\x1b[0m`;
+  const dim = (s) => color ? `\x1b[2m${s}\x1b[0m` : s;
+  const parts = [];
+  const model = input && input.model && (input.model.display_name || input.model.id);
+  const ctx = input && input.context_window && typeof input.context_window.used_percentage === 'number' ? input.context_window.used_percentage : null;
+  if (model) parts.push(model + (ctx != null ? dim(` · ctx ${Math.round(ctx)}%`) : ''));
+  if (input && input.rate_limits_available === false) parts.push(dim('no plan limits (API key, Bedrock or Vertex)'));
+  else {
+    const snap = snapshotFrom(input, now);
+    const five = snap && snap.five, week = snap && snap.week;
+    parts.push(five ? `5h ${paint(five.pct, pctText(five.pct))}${dim(' · ' + left(five.resets - now) + ' left')}` : dim('5h —'));
+    parts.push(week ? `week ${paint(week.pct, pctText(week.pct))}${dim(' · resets ' + (week.resets - now > 24 * H ? DAYS[new Date(week.resets).getDay()] + ' ' : '') + hm(week.resets))}` : dim('week —'));
+  }
+  return parts.join(dim(' │ '));
+}
+
+// A status line the user had before `statusline install` keeps running, in front of ours. Process start can take
+// seconds on a busy Windows machine, so when it runs out of time its last good line is shown instead of nothing.
+function previousLine(home, raw, timeout = 2000) {
+  const f = previousFile(home);
+  if (!fs.existsSync(f)) return null;
+  let prev; try { prev = JSON.parse(readTextFile(f)).statusLine; } catch (e) { return null; }
+  if (!prev || prev.type !== 'command' || typeof prev.command !== 'string') return null;
+  const cache = f.replace(/\.json$/, '.last');
+  const r = spawnSync(prev.command, { shell: true, input: raw, encoding: 'utf8', timeout, windowsHide: true });
+  const line = String(r.stdout || '').split('\n')[0].trimEnd();
+  if (line && !r.error) { try { fs.writeFileSync(cache, line); } catch (e) { } return line; }
+  try { return fs.readFileSync(cache, 'utf8') || null; } catch (e) { return null; }
+}
+
+// What `glassbox statusline` does on each refresh: log, then print.
+export function statusline(input, opts = {}) {
+  const home = opts.home || claudeHome();
+  const now = opts.now != null ? opts.now : Date.now();
+  try { logSnapshot(home, snapshotFrom(input, now)); } catch (e) { } // a full disk must not blank the status bar
+  const ours = statusText(input, { now, color: opts.color });
+  let theirs = null; try { theirs = previousLine(home, opts.raw != null ? opts.raw : JSON.stringify(input || {}), opts.previousTimeout); } catch (e) { }
+  return theirs ? `${theirs} │ ${ours}` : ours;
+}
+
+// ---------------------------------------------------------------------------
+// install / uninstall
+// ---------------------------------------------------------------------------
+export const STATUS_RE = /\bglassbox(?:-trace)?(?:\.mjs)?["']?\s+statusline\b/;
+const ours = (sl) => sl && typeof sl.command === 'string' && STATUS_RE.test(sl.command);
+
+export function installStatusLine(opts = {}) {
+  const home = opts.home || claudeHome();
+  const file = settingsPath(home);
+  let settings = {};
+  if (fs.existsSync(file)) { try { settings = JSON.parse(readTextFile(file)); } catch (e) { throw new Error(`${file} is not valid JSON — fix it first (nothing was changed)`); } fs.copyFileSync(file, file + '.glassbox-backup'); }
+  let kept = null;
+  if (settings.statusLine && !ours(settings.statusLine)) {
+    const prev = previousFile(home); fs.mkdirSync(path.dirname(prev), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(prev, JSON.stringify({ savedAt: new Date().toISOString(), statusLine: settings.statusLine }, null, 2) + '\n');
+    kept = settings.statusLine.command || '(not a command)';
+  }
+  const command = `${opts.command} statusline${opts.noColor ? ' --no-color' : ''}`;
+  settings.statusLine = { type: 'command', command, padding: 0 };
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
+  return { file, command, kept };
+}
+
+export function uninstallStatusLine(opts = {}) {
+  const home = opts.home || claudeHome();
+  const file = settingsPath(home), prev = previousFile(home);
+  if (!fs.existsSync(file)) return { file, removed: false, restored: null };
+  const settings = JSON.parse(readTextFile(file));
+  if (!ours(settings.statusLine)) return { file, removed: false, restored: null };
+  fs.copyFileSync(file, file + '.glassbox-backup');
+  let restored = null;
+  if (fs.existsSync(prev)) { try { restored = JSON.parse(readTextFile(prev)).statusLine || null; } catch (e) { } fs.unlinkSync(prev); }
+  try { fs.unlinkSync(prev.replace(/\.json$/, '.last')); } catch (e) { }
+  if (restored) settings.statusLine = restored; else delete settings.statusLine;
+  fs.writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
+  return { file, removed: true, restored: restored ? restored.command || '(restored)' : null };
+}