@drakulavich/zapara 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this project are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-09-22
+
+### Changed
+- The week grid's `peak` column is painted in a TTY with the color of the level its index falls in, by the same thresholds `zapara status` reads a level from; `--no-color` and a pipe are unchanged.
+- The status file's `index` and `level` are the load of the sixty minutes ending at `asOf`, not of the calendar hour that contains it: the number no longer drops to nothing at every hour boundary (90 at 11:59:30, 6 at 12:00:30 on one machine) and no longer climbs through the hour as the bucket fills. `Day.live` in `--json` carries that bucket on the open day. Same formula, same norms; `schema` stays 1.
+
 ## [0.4.0] - 2026-09-21
 
 ### Changed

package/README.md

@@ -135,7 +135,7 @@ This one comes from the same `busy-week` fixture as the pictures above. A headle
 | `--json` | Print the whole window as one JSON document instead of a table. |
 | `--projects <dir>` | Read this directory instead of `~/.claude/projects`. |
 | `--out <path>` | Where `card` writes; the extension picks the format. |
-| `--no-color` | Plain glyphs with no ANSI codes. `NO_COLOR` in the environment does the same. |
+| `--no-color` | Plain glyphs and peaks with no ANSI codes. `NO_COLOR` in the environment does the same. |
 | `-h`, `--help` | Usage, exit 0. |
 | `-V`, `--version` | The version from `package.json`, exit 0. |
 
@@ -143,7 +143,7 @@ Levels: calm 0–29, warming 30–59, heating 60–84, fried 85–100.
 
 The grid and the day print a text table when stdout is a terminal and JSON otherwise, so `zapara | cat` prints JSON; no flag forces text in a pipe yet. `card` and `status` write their file and print their lines whether piped or not. `card --json` is the exception: it prints the card's data and writes no file. `--json` changes nothing for `status`, whose line is already JSON and whose file is written either way.
 
-Exit codes are 0 on success, 1 when the projects directory is missing or cannot be read, when `status` cannot write its file, or when `card` cannot write its picture (four different messages, none with a path), and 2 for a usage error such as a bad date, an unknown flag or a value flag given twice, which prints one line and a hint to `--help`. A window with no data prints an empty grid and exits 0.
+Exit codes are 0 on success, 1 for a failure zapara can name, which prints one line to stderr and never a path: the projects directory missing or unreadable, `status` unable to write its file, `card` unable to write its picture or to find a browser engine, and whatever else goes wrong below the command line; and 2 for a usage error such as a bad date, an unknown flag or a value flag given twice, which prints one line and a hint to `--help`. A window with no data prints an empty grid and exits 0.
 
 ## Status line
 
@@ -159,8 +159,8 @@ A status line wants one number every thirty seconds and cannot wait half a secon
 | `asOf` | When the snapshot was taken, ISO 8601 UTC: the `Day.asOf` of the base spec, the `now` of this run. A reader decides staleness from this field, never from the file's mtime. |
 | `date` | The local calendar day the numbers describe, `YYYY-MM-DD`. |
 | `hour` | The local hour that contains `asOf`, `0`..`23`. |
-| `index` | That hour's load index, `0`..`100`, or `null` when the hour has no activity yet. |
-| `level` | That hour's level, `Calm`, `Warming`, `Heating` or `Fried`, or `null` with `index`. A reader colors by this field so it never needs the thresholds. |
+| `index` | The load index of the sixty minutes ending at `asOf`, `0`..`100`, or `null` when they hold no session. It does not reset at an hour boundary: the hour buckets of `zapara today` are calendar hours, this one is the clock's last hour. |
+| `level` | That index's level, `Calm`, `Warming`, `Heating` or `Fried`, or `null` with `index`. A reader colors by this field so it never needs the thresholds. |
 | `peak` | The day's peak index so far, or `null` on a day with no activity. |
 | `activeMin` | Minutes of your presence in the day so far: the 5-minute slots covered by your actions and the gaps of at most 10 minutes between them; `0` on a day with no action of yours. |
 | `streakMin` | Minutes of your live presence streak as of `asOf`: from the streak's first action to `asOf`, when your last action is no more than 10 minutes before `asOf`; `0` once you have been away longer. It keeps growing while you sit there, and it does not reset at an hour boundary. |
@@ -258,6 +258,6 @@ bun run check    # tsc --noEmit, then the test suite under TZ=UTC
 
 Tests are fixture-driven: they build or load transcripts in the real Claude Code format and assert the statistics that come out of the public seams, `analyze()`, `report()` and the CLI itself. No test imports the parser, the deriver or the scanner, so refactoring internals never touches a test. The rules every change follows are in [CLAUDE.md](CLAUDE.md), the design is in [docs/superpowers/specs/2026-09-17-zapara-design.md](docs/superpowers/specs/2026-09-17-zapara-design.md), and every change is recorded in [CHANGELOG.md](CHANGELOG.md).
 
-## License
+---
 
-MIT. See [LICENSE](LICENSE).
+<p align="center">Made with ❤️ and 🥤 energy under <a href="LICENSE">MIT License</a></p>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/zapara",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Cognitive load index for people driving Claude Code, computed locally from transcripts",
   "license": "MIT",
   "author": "Anton Yakutovich",

package/src/analyze.ts

@@ -1,12 +1,11 @@
-import { derive } from "./derive.ts";
+import { compareStrings, derive } from "./derive.ts";
 import { parseTranscript } from "./parse.ts";
 import type { Day, Transcript, Window } from "./types.ts";
 
-// The core's entry point: transcripts already in memory, in the real JSONL format, in.
-// Day[] out. Transcripts are sorted by path so file discovery order cannot change a result.
+// Sorted by path so file discovery order cannot change a result.
 export function analyze(transcripts: Transcript[], w: Window): Day[] {
   const events = [...transcripts]
-    .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+    .sort((a, b) => compareStrings(a.path, b.path))
     .flatMap((t) => parseTranscript(t.text));
   return derive(events, w);
 }

package/src/card.ts

@@ -1,7 +1,5 @@
-// Card data: which of four characters a window is, the sentence behind it, the
-// peak hour, the load spectrum and three highlights, every value already
-// formatted for the page. Pure: Day[] in, CardData out. Nothing here knows a
-// date, a path or a file, so nothing here can leak one.
+// Pure: Day[] in, CardData out, every value already formatted for the page.
+// Nothing here knows a date, a path or a file, so nothing here can leak one.
 import { formatCount, formatTokens, plural } from "./format.ts";
 import { NORMS, WEIGHTS } from "./score.ts";
 import type { Day, HourBucket, Level, Score } from "./types.ts";
@@ -34,9 +32,8 @@ const MOTTOS: Record<Character, string> = {
   marathoner: "You do not stop while it compiles.",
   nightOwl: "The best commits happen after midnight.",
 };
-// Ranking norms for the third highlight: a value over its norm says how remarkable
-// it is next to the others. Sums are per active hour. These rank a picture and
-// never touch the index; the index's own norms stay in score.ts.
+// Rank the third highlight, per active hour. They never touch the index, whose
+// norms stay in score.ts.
 const CARD_NORMS = { reportsPerHour: 12, tokensPerHour: 65_000, interruptsPerHour: 3, latePercent: 25 } as const;
 const OWNED: Record<Character, [HighlightKey, HighlightKey]> = {
   conductor: ["peakSessions", "contextSwitches"],
@@ -94,15 +91,15 @@ export function cardData(days: Day[], w: { days: number }): CardData | null {
   const max = (f: (b: Active) => number): number => active.reduce((a, b) => Math.max(a, f(b)), 0);
   const count = (level: Level): number => active.filter((b) => b.score.level === level).length;
 
-  // Each share is the fraction of that character's maximum possible points the
-  // window collected, so a 10-point component competes fairly with a 40-point one.
+  // A share is the fraction of the character's maximum points, so a 10-point
+  // component competes fairly with a 40-point one.
   const shares: Record<Character, number> = {
     conductor: sum((b) => b.score.parts.parallel + b.score.parts.pace) / ((WEIGHTS.parallel + WEIGHTS.pace) * n),
     supervisor: sum((b) => b.score.parts.supervision + b.score.parts.reading) / ((WEIGHTS.supervision + WEIGHTS.reading) * n),
     marathoner: sum((b) => b.score.parts.streak) / (WEIGHTS.streak * n),
     nightOwl: sum((b) => b.score.parts.late) / (WEIGHTS.late * n),
   };
-  // Strict > keeps the earlier of equal shares: CHARACTERS is the tie order.
+  // Strict >: CHARACTERS is the tie order.
   const character = CHARACTERS.reduce((best, c) => (shares[c] > shares[best] ? c : best));
 
   const maxSessions = max((b) => b.sessions);
@@ -143,7 +140,7 @@ export function cardData(days: Day[], w: { days: number }): CardData | null {
     lateShare: late / CARD_NORMS.latePercent,
   };
   const owned = OWNED[character];
-  // A late-night number on anyone but the Night Owl is the kind of thing they would hide.
+  // A late-night number belongs to the Night Owl alone.
   const rest = POOL.filter((k) => !owned.includes(k) && (k !== "lateShare" || character === "nightOwl"));
   const third = rest.reduce((best, k) => (norms[k] > norms[best] ? k : best));
   const highlights = [...owned, third].map((key) => ({ key, value: values[key], caption: CAPTIONS[key] }));

package/src/cardhtml.ts

@@ -1,7 +1,6 @@
-// The card page: one self-contained HTML document from CardData and the embedded
-// assets. Pure: strings in, string out. Nothing is escaped because nothing from a
-// transcript reaches this file: only CardData's fixed strings and formatted numbers.
-// The look is the table in docs/superpowers/specs/2026-09-18-zapara-card-design.md.
+// Nothing is escaped because nothing from a transcript reaches this file: only
+// CardData's fixed strings and formatted numbers. The look is the table in
+// docs/superpowers/specs/2026-09-18-zapara-card-design.md.
 import type { CardData, Character, Segment } from "./card.ts";
 import type { Level } from "./types.ts";
 
@@ -10,10 +9,8 @@ export type CardAssets = {
   characters: string;
 };
 
-// Where each character sits on the sheet, as fractions [x, y, w, h] of its side,
-// measured on the current assets/characters.webp. The box is scaled so the
-// rectangle's longer side is BOX px and centred at CENTRE, with CSS background-size
-// and background-position, so no cropping happens anywhere.
+// Fractions [x, y, w, h] of the sheet's side, measured on assets/characters.webp.
+// Scaled so the longer side is BOX px, centred at CENTRE; nothing is cropped.
 export const CHARACTER_RECTS: Record<Character, [number, number, number, number]> = {
   conductor: [0.02, 0.01, 0.53, 0.543],
   supervisor: [0.55, 0.07, 0.38, 0.505],
@@ -23,7 +20,7 @@ export const CHARACTER_RECTS: Record<Character, [number, number, number, number]
 const BOX = 360;
 const CENTRE = { x: 195, y: 300 };
 
-// Streak accent, its rgb for alpha gradients, and the light shade for the repo link.
+// main, its rgb for alpha gradients, and the light shade for the repo link.
 const ACCENT: Record<Character, { main: string; rgb: string; light: string }> = {
   conductor: { main: "#8b5cf6", rgb: "139,92,246", light: "#c4b5fd" },
   supervisor: { main: "#22d3ee", rgb: "34,211,238", light: "#a5f3fc" },

package/src/derive.ts

@@ -1,11 +1,14 @@
 import { score } from "./score.ts";
-import type { Day, Event, EventKind, HourBucket, Metrics, Totals, Window } from "./types.ts";
+import type { Day, Event, EventKind, HourBucket, LiveBucket, Metrics, Totals, Window } from "./types.ts";
 
 export const LOOKBACK_MS = 3 * 60 * 60 * 1000;
 export const GAP_MS = 10 * 60 * 1000;
 export const SLOT_MS = 5 * 60 * 1000;
+const LIVE_MS = 60 * 60 * 1000;
 const LATE_HOURS = new Set([23, 0, 1, 2, 3, 4, 5]);
 
+// Not localeCompare: a result must not depend on the locale.
+export const compareStrings = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
 const pad2 = (n: number) => String(n).padStart(2, "0");
 export const localDate = (d: Date) => `${d.getFullYear()}-${pad2(d.getMonth() + 1)}-${pad2(d.getDate())}`;
 const parseDate = (s: string): Date => {
@@ -30,25 +33,64 @@ const emptyMetrics = (): Metrics => ({
   decisions: 0, contextSwitches: 0, activeMin: 0, streakMin: 0, lateNight: false,
 });
 
-// Presence is every action the human takes: what they typed, and the three ways
-// they answer or stop the agent. Agent records (`activity`, `report`, `output`)
-// and the agent's own asks (`question`, `plan_review`) are never presence.
+// Presence is the human's own actions only: agent records and the agent's asks
+// are never presence, because presence answers "is it time to rest?".
 const PRESENCE: ReadonlySet<EventKind> = new Set<EventKind>(["prompt", "interrupt", "reject", "answer"]);
 
 type Acc = { m: Metrics; sessions: Set<string>; slots: Set<number>; lastPromptSession: string | null; maxStreakMs: number; lastPresence: { ts: number; streakStart: number } | null };
+const newAcc = (): Acc => ({ m: emptyMetrics(), sessions: new Set(), slots: new Set(), lastPromptSession: null, maxStreakMs: 0, lastPresence: null });
 
-// Walks the sorted, look-back-filtered events once, keyed by "date|hour",
-// tracking the running presence streak (which may start before startMs) and
-// accumulating each bucket's raw counts.
-//
-// Presence is the human's: both the streak and the covered slots are built from
-// the PRESENCE kinds alone, because both answer "is it time to rest?". Agents
-// that work on while the human is away must not keep a streak alive or fill the
-// day, so `activity` is left with session liveness and nothing else.
-//
-// Presence events before startMs update presence only: they are never counted in
-// a bucket, and neither are the slots they cover before startMs, but a span from
-// such an event into the window still covers the window's first slots.
+// Inside a streak the human sat through the gap, so a pair of actions covers
+// every slot between them; an action that starts a streak covers only its own.
+const coverage = (prevTs: number | null, streakStart: number, e: Event): { from: number; to: number; streakStart: number } => {
+  const to = Math.floor(e.ts / SLOT_MS);
+  if (prevTs !== null && e.ts - prevTs <= GAP_MS) return { from: Math.floor(prevTs / SLOT_MS), to, streakStart };
+  return { from: to, to, streakStart: e.ts };
+};
+
+// The counts an hour bucket and the live bucket share. `streakStart` is the
+// caller's: a streak may have begun before this accumulator's window. The streak
+// kept is the longest seen, not the one the window ended on, or a single prompt
+// after a break would erase the run.
+function accumulate(a: Acc, e: Event, streakStart: number): void {
+  if (PRESENCE.has(e.kind)) {
+    a.maxStreakMs = Math.max(a.maxStreakMs, e.ts - streakStart);
+    a.lastPresence = { ts: e.ts, streakStart }; // for the day's live streak
+  }
+  switch (e.kind) {
+    case "activity":
+      a.sessions.add(e.sessionId);
+      break;
+    case "prompt":
+      a.m.prompts++;
+      if (a.lastPromptSession !== null && a.lastPromptSession !== e.sessionId) a.m.contextSwitches++;
+      a.lastPromptSession = e.sessionId;
+      break;
+    case "report": a.m.reports++; break;
+    case "output": a.m.outputTokens += e.tokens ?? 0; break;
+    case "interrupt": a.m.interrupts++; break;
+    case "reject": a.m.rejects++; break;
+    case "question": a.m.questions++; break;
+    case "plan_review": a.m.plans++; break;
+    case "mode_change": a.m.modeSwitches++; break;
+  }
+}
+
+// `lateNight` is the caller's: an hour's own label, or the hour of `now` for the
+// live bucket. A fresh accumulator is an empty hour and scores null.
+function finish(a: Acc, lateNight: boolean): LiveBucket {
+  const m = a.m;
+  m.sessions = a.sessions.size;
+  m.activeMin = a.slots.size * 5;
+  m.streakMin = Math.round(a.maxStreakMs / 60000);
+  m.decisions = m.interrupts + m.rejects + m.questions + m.plans + m.modeSwitches;
+  m.lateNight = lateNight;
+  return { ...m, score: score(m) };
+}
+
+// The 24 hour buckets, keyed "date|hour". Events before startMs are look-back:
+// they move the streak but enter no bucket, though a span from one into the
+// window still covers the window's first slots.
 function foldEvents(sorted: Event[], startMs: number): { acc: Map<string, Acc>; carried: { ts: number; streakStart: number } | null } {
   const acc = new Map<string, Acc>(); // key "date|hour"
   const key = (ts: number): string => {
@@ -57,7 +99,7 @@ function foldEvents(sorted: Event[], startMs: number): { acc: Map<string, Acc>;
   };
   const get = (k: string): Acc => {
     let a = acc.get(k);
-    if (!a) { a = { m: emptyMetrics(), sessions: new Set(), slots: new Set(), lastPromptSession: null, maxStreakMs: 0, lastPresence: null }; acc.set(k, a); }
+    if (!a) { a = newAcc(); acc.set(k, a); }
     return a;
   };
 
@@ -66,76 +108,53 @@ function foldEvents(sorted: Event[], startMs: number): { acc: Map<string, Acc>;
   let carried: { ts: number; streakStart: number } | null = null;
   for (const e of sorted) {
     if (PRESENCE.has(e.kind)) {
-      const slot = Math.floor(e.ts / SLOT_MS);
-      // A presence event covers its own slot. Inside a streak the human sat
-      // through the gap too, so the pair also covers every slot between them; an
-      // event that starts a streak covers nothing behind it.
-      let from = slot;
-      if (prevPresenceTs !== null && e.ts - prevPresenceTs <= GAP_MS) from = Math.floor(prevPresenceTs / SLOT_MS);
-      else streakStart = e.ts;
-      for (let s = from; s <= slot; s++) {
+      const c = coverage(prevPresenceTs, streakStart, e);
+      streakStart = c.streakStart;
+      for (let s = c.from; s <= c.to; s++) {
         const slotStart = s * SLOT_MS;
         if (slotStart >= startMs) get(key(slotStart)).slots.add(s); // a slot belongs to the bucket of its start
       }
       prevPresenceTs = e.ts;
-      // The last human action before the window opens, kept for the first day:
-      // a person still at the keyboard at 23:58 is still in that streak at
-      // 00:03, and the day they are looking at holds nothing yet.
+      // A person at the keyboard at 23:58 is still in that streak at 00:03,
+      // and the day they are looking at holds nothing yet.
       if (e.ts < startMs) carried = { ts: e.ts, streakStart };
     }
     if (e.ts < startMs) continue; // look-back: presence bookkeeping only
-    const a = get(key(e.ts));
-    // The hour's streak is the longest it saw, not the one it happened to end
-    // on: a single prompt after a break would otherwise erase a run of hours.
-    // A streak is longest at its last event, and that event lies in some hour,
-    // so the maximum over hours is the run's true length.
+    accumulate(get(key(e.ts)), e, streakStart);
+  }
+  return { acc, carried };
+}
+
+// The sixty minutes ending at `now`, by the rule an hour bucket uses. Presence
+// runs from the first event, so a streak older than the window is measured from
+// where it began. Events before the day's start count here, unlike in a bucket:
+// the window is a clock's hour, not a calendar's.
+function foldLive(sorted: Event[], nowMs: number): Acc {
+  const a = newAcc();
+  const fromMs = nowMs - LIVE_MS;
+  const inWindow = (t: number): boolean => t > fromMs && t <= nowMs;
+  let prevPresenceTs: number | null = null;
+  let streakStart = 0;
+  for (const e of sorted) {
     if (PRESENCE.has(e.kind)) {
-      a.maxStreakMs = Math.max(a.maxStreakMs, e.ts - streakStart);
-      a.lastPresence = { ts: e.ts, streakStart }; // the bucket's last, for the day's live streak
-    }
-    switch (e.kind) {
-      case "activity":
-        a.sessions.add(e.sessionId);
-        break;
-      case "prompt":
-        a.m.prompts++;
-        if (a.lastPromptSession !== null && a.lastPromptSession !== e.sessionId) a.m.contextSwitches++;
-        a.lastPromptSession = e.sessionId;
-        break;
-      case "report": a.m.reports++; break;
-      case "output": a.m.outputTokens += e.tokens ?? 0; break;
-      case "interrupt": a.m.interrupts++; break;
-      case "reject": a.m.rejects++; break;
-      case "question": a.m.questions++; break;
-      case "plan_review": a.m.plans++; break;
-      case "mode_change": a.m.modeSwitches++; break;
+      const c = coverage(prevPresenceTs, streakStart, e);
+      streakStart = c.streakStart;
+      for (let s = c.from; s <= c.to; s++) if (inWindow(s * SLOT_MS)) a.slots.add(s);
+      prevPresenceTs = e.ts;
     }
+    if (inWindow(e.ts)) accumulate(a, e, streakStart);
   }
-  return { acc, carried };
+  return a;
 }
 
-// Builds one Day's 24 hour buckets from the accumulated counts, scores each,
-// and rolls up totals, peak and mean.
 function buildDay(date: string, acc: Map<string, Acc>): Day {
   const buckets: HourBucket[] = [];
-  // The day's last human action: the last one of the highest hour that saw any.
-  // Hours run in time order, so the last write wins.
+  // Hours run in time order, so the last write is the day's last action.
   let lastPresence: { ts: number; streakStart: number } | null = null;
   for (let hour = 0; hour < 24; hour++) {
     const a = acc.get(`${date}|${hour}`);
-    const m = a ? a.m : emptyMetrics();
-    if (a) {
-      if (a.lastPresence) lastPresence = a.lastPresence;
-      m.sessions = a.sessions.size;
-      m.activeMin = a.slots.size * 5;
-      m.streakMin = Math.round(a.maxStreakMs / 60000);
-    }
-    m.decisions = m.interrupts + m.rejects + m.questions + m.plans + m.modeSwitches;
-    // lateNight is a property of the hour label, so it is set on every bucket,
-    // including empty ones; score() returns null for buckets without
-    // sessions, so an empty late hour scores nothing.
-    m.lateNight = LATE_HOURS.has(hour);
-    buckets.push({ ...m, hour, score: score(m) });
+    if (a?.lastPresence) lastPresence = a.lastPresence;
+    buckets.push({ ...finish(a ?? newAcc(), LATE_HOURS.has(hour)), hour });
   }
   const scored = buckets.filter((b) => b.score !== null);
   const totals: Totals = buckets.reduce((t, b) => ({
@@ -158,24 +177,25 @@ function buildDay(date: string, acc: Map<string, Acc>): Day {
 
 export function derive(events: Event[], w: Window): Day[] {
   const { startMs, endMs, cutoffMs, dates } = windowBounds(w);
+  // sort() is stable, so events equal on both keys keep their input order.
   const sorted = events
-    .map((e, i) => ({ e, i }))
-    .filter(({ e }) => e.ts >= cutoffMs && e.ts < endMs && (!w.now || e.ts <= w.now.getTime()))
-    .sort((a, b) => a.e.ts - b.e.ts || (a.e.sessionId < b.e.sessionId ? -1 : a.e.sessionId > b.e.sessionId ? 1 : 0) || a.i - b.i)
-    .map(({ e }) => e);
+    .filter((e) => e.ts >= cutoffMs && e.ts < endMs && (!w.now || e.ts <= w.now.getTime()))
+    .sort((a, b) => a.ts - b.ts || compareStrings(a.sessionId, b.sessionId));
   const { acc, carried } = foldEvents(sorted, startMs);
   const days = dates.map((date) => buildDay(date, acc));
-  // Only the first day can be preceded by the look-back, and only a day with no
-  // action of its own needs it: the streak that was running when the window
-  // opened is still the one the person is in. It reaches `presence` and nothing
-  // else — no bucket, no total, no active minute belongs to a day before this one.
+  // Only a first day with no action of its own borrows the look-back's streak,
+  // and only into `presence`: no bucket, total or active minute crosses back.
   const first = days[0];
   if (first && first.presence === null && carried) {
     first.presence = { lastAt: new Date(carried.ts).toISOString(), streakStartAt: new Date(carried.streakStart).toISOString() };
   }
   if (w.now) {
     const today = localDate(w.now);
-    for (const d of days) if (d.date === today) d.asOf = w.now.toISOString();
+    const open = days.find((d) => d.date === today);
+    if (open) {
+      open.asOf = w.now.toISOString();
+      open.live = finish(foldLive(sorted, w.now.getTime()), LATE_HOURS.has(w.now.getHours()));
+    }
   }
   return days;
 }

package/src/format.ts

@@ -1,8 +1,5 @@
-// Compact number formats shared by the card and the week footer. Pure: no
-// imports from node:/Bun, no clock, no file system.
-
-// Compact formats with a fixed longest form of five characters, so the layout
-// is sized once. Decimals are truncated, not rounded: 9.96M stays "9.9M".
+// Longest form is five characters, so the layout is sized once. Decimals are
+// truncated, not rounded: 9.96M stays "9.9M".
 function ladder(n: number): string {
   if (n >= 1e12) return "999B+";
   for (const [unit, size] of [["B", 1e9], ["M", 1e6], ["k", 1e3]] as const) {
@@ -16,5 +13,4 @@ function ladder(n: number): string {
 export const formatCount = (n: number): string => (n < 10_000 ? String(n) : ladder(n));
 export const formatTokens = (n: number): string => (n < 1000 ? String(n) : ladder(n));
 
-// "1 session", "5 sessions": a count with its noun, singular only for exactly one.
 export const plural = (n: number, one: string, many = `${one}s`, count = formatCount): string => `${count(n)} ${n === 1 ? one : many}`;

package/src/image.ts

@@ -1,14 +1,12 @@
-// The card's shell: the only module that reads the card assets, opens a
-// Bun.WebView or a Bun.Image, and writes a file. Everything it writes is the one
-// file the person named; nothing here prints.
+// The only module that reads the card assets, opens a Bun.WebView or Bun.Image,
+// and writes the card.
 import { readFile, writeFile } from "node:fs/promises";
 import type { CardAssets } from "./cardhtml.ts";
 
 const ASSETS = new URL("../assets/", import.meta.url);
 const FILES = ["fonts/inter-400.woff2", "fonts/inter-700.woff2", "fonts/inter-800.woff2", "fonts/jetbrains-mono-500.woff2", "characters.webp"] as const;
 
-// Reads the five files next to the source. A missing, unreadable or empty one is
-// a broken install, reported without a path: the CLI never prints one.
+// A missing or empty asset is a broken install, reported without a path.
 export async function loadAssets(): Promise<CardAssets> {
   let parts: string[];
   try {
@@ -28,14 +26,9 @@ const WIDTH = 2400;
 const HEIGHT = 1260;
 const READY = 'document.fonts.ready.then(() => document.fonts.status === "loaded" && Array.from(document.images).every((i) => i.complete))';
 
-// Writes the page as is for `.html`; otherwise photographs it at 2400x1260 and
-// writes PNG or WebP. The 15s budget bounds the whole render (construct, navigate,
-// poll, screenshot, resize, encode), raced against a single timer; the view is
-// closed on every path. Any engine failure (constructor, navigate, evaluate,
-// screenshot) is mapped to one line that never quotes the engine's own text; the
-// timeout error passes through unchanged. A failed write (missing directory, no
-// permission, a directory in the way, a read-only file system) becomes one line
-// that names no path, because the node error quotes the whole path.
+// The budget bounds the whole render, raced against one timer; the view is
+// closed on every path. An engine failure becomes one line that never quotes
+// the engine's text; the timeout error passes through unchanged.
 export async function renderCard(html: string, out: string, timeoutMs = 15_000): Promise<void> {
   const lower = out.toLowerCase();
   if (lower.endsWith(".html")) {
@@ -71,8 +64,7 @@ export async function renderCard(html: string, out: string, timeoutMs = 15_000):
   await write(out, bytes);
 }
 
-// The only place the card is written. Every failure is the same one line: the
-// error node raises quotes the path in full, and the CLI never prints one.
+// One line for every failure: node's error quotes the path, and the CLI never prints one.
 async function write(out: string, data: string | Uint8Array): Promise<void> {
   try {
     await writeFile(out, data);

package/src/index.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env bun
-// zapara CLI. Argument parsing, the clock, stdout and exit codes live here; everything else is pure.
+// Argument parsing, the clock, stdout and exit codes live here; everything else is pure.
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -13,9 +13,8 @@ import { renderStatus, statusOf } from "./status.ts";
 import { writeStatus } from "./statusfile.ts";
 import type { Day } from "./types.ts";
 
-// Read lazily, only when --version is actually handled, so a broken install
-// (missing or corrupt package.json) fails inside the guarded catch below
-// instead of throwing at module load, before any try/catch is in place.
+// Read only when --version is handled, so a broken package.json fails inside
+// the guarded catch instead of at module load.
 function version(): string {
   const parsed: unknown = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
   if (typeof parsed === "object" && parsed !== null && typeof (parsed as { version?: unknown }).version === "string") {
@@ -45,22 +44,18 @@ options:
 levels: calm 0-29  warming 30-59  heating 60-84  fried 85-100`;
 const HINT = "run 'zapara --help' for usage";
 
-// A grid is the window as one cell per hour; a day is one date as one row per
-// hour; status is today, written to the status file for a status line to read.
 type Args = { command: "grid" | "day" | "card" | "status"; to: string; days: number; explain: boolean; json: boolean; out: string; projects: string; color: boolean };
 
 class UsageError extends Error {}
-// Thrown only at a flag position (never when a token was consumed as another
-// flag's value, e.g. `--to --help`), so `main()` can short-circuit to exit 0
-// without parseArgs having to also validate the rest of a help/version call.
+// Thrown only at a flag position, never for a token consumed as another flag's
+// value (`--to --help`).
 class HelpRequested extends Error {}
 class VersionRequested extends Error {}
 
 const DATE = /^(\d{4})-(\d{2})-(\d{2})$/;
 
-// A usage error quotes the offending value only when it is short, printable ASCII
-// with no path separator: the CLI never prints a filesystem path or an escape,
-// not even one the person typed.
+// A usage error quotes the value only when it is short, printable ASCII with no
+// path separator: the CLI never prints a path or an escape, even one typed in.
 const quotable = (v: string): boolean => /^[\x21-\x7e]{1,24}$/.test(v) && !/[\/\\]/.test(v);
 const got = (v: string): string => (quotable(v) ? `, got ${v}` : "");
 const named = (v: string): string => (quotable(v) ? ` ${v}` : "");
@@ -73,7 +68,6 @@ function validDate(s: string): boolean {
   return dt.getFullYear() === y && dt.getMonth() === mo - 1 && dt.getDate() === d;
 }
 
-// A date on the command line: YYYY-MM-DD, today or yesterday, in local time.
 function resolveDate(what: string, s: string, now: Date): string {
   if (s === "today") return localDate(now);
   if (s === "yesterday") return localDate(new Date(now.getFullYear(), now.getMonth(), now.getDate() - 1));
@@ -81,15 +75,13 @@ function resolveDate(what: string, s: string, now: Date): string {
   return s;
 }
 
-// Calendar days from one date to another, inclusive; UTC arithmetic so a DST day is still one day.
+// UTC arithmetic, so a DST day is still one day.
 function spanDays(from: string, to: string): number {
   const utc = (s: string): number => { const [y = 0, m = 0, d = 0] = s.split("-").map(Number); return Date.UTC(y, m - 1, d); };
   return Math.round((utc(to) - utc(from)) / 86_400_000) + 1;
 }
 
-// The window from its flags: --days ending today or at --to, or --from/--to, both
-// inclusive. --from with --days is one length too many. Checks run in the order
-// a reader meets the flags in --help.
+// Checks run in the order a reader meets the flags in --help.
 function windowOf(days: string | null, from: string | null, to: string | null, defaultDays: number, now: Date): { to: string; days: number } {
   if (from !== null && days !== null) throw new UsageError("--from sets the length; drop --days");
   if (days !== null && (!/^\d+$/.test(days) || Number(days) < 1 || Number(days) > 90)) throw new UsageError(`--days must be 1..90${got(days)}`);
@@ -110,19 +102,16 @@ function parseArgs(argv: string[], now: Date, env: NodeJS.ProcessEnv, isTTY: boo
   let jsonFlag = false;
   let outGiven = false;
   const positional: string[] = [];
-  // A value flag given twice is a usage error, not the last value winning
-  // silently; bare flags (--json, --explain, --no-color) are idempotent and stay untracked.
+  // A value flag given twice is a usage error; bare flags are idempotent and untracked.
   const seen = new Set<string>();
   for (let i = 0; i < argv.length; i++) {
     let arg = argv[i]!;
-    // `--days=30` is `--days 30`. A flag that takes no value refuses an inline one.
     let inline: string | null = null;
     const eq = arg.startsWith("--") ? arg.indexOf("=") : -1;
     if (eq > 0) { inline = arg.slice(eq + 1); arg = arg.slice(0, eq); }
     const bare = (): void => { if (inline !== null) throw new UsageError(`unknown flag${named(argv[i]!)}`); };
-    // A missing value or one that looks like another flag is a usage error,
-    // never treated as this flag's value (e.g. `--projects --json`). Only --days
-    // takes a negative number as a value, so `--days -1` reaches the range check.
+    // A value that looks like another flag is a usage error (`--projects --json`);
+    // only --days accepts a negative number, so `--days -1` reaches the range check.
     const value = (negativeNumberIsValue = false): string => {
       let v: string;
       if (inline !== null) v = inline;
@@ -161,19 +150,16 @@ function parseArgs(argv: string[], now: Date, env: NodeJS.ProcessEnv, isTTY: boo
   else if (word === "today" || word === "yesterday" || DATE.test(word)) { a.command = "day"; a.to = resolveDate("date", word, now); a.days = 1; }
   else throw new UsageError(`unknown command${named(word)} (try today, yesterday, a date, card or status)`);
 
-  // Both commands fix their own window: a named day is the date given, status is today.
   if (a.command === "day" || a.command === "status") {
     if (days !== null || from !== null || to !== null) throw new UsageError(`--days, --from and --to do not apply to ${a.command === "day" ? "a named day" : "status"}`);
   } else {
-    // Two weeks make a pattern; a week makes a picture of one week.
     ({ to: a.to, days: a.days } = windowOf(days, from, to, a.command === "card" ? 14 : 7, now));
   }
-  // Tables turn into JSON in a pipe; the card is a file either way, so only an explicit --json switches it.
+  // The card is a file either way, so only an explicit --json switches it.
   a.json = a.command === "card" ? jsonFlag : jsonFlag || !isTTY;
   if (a.command !== "day" && a.explain) throw new UsageError("--explain applies to a named day only");
   if (a.command !== "card" && outGiven) throw new UsageError("--out applies to card only");
-  // The value is printed back verbatim in `wrote \u2026`, so it must be one plain line:
-  // no control character, and the message never quotes it.
+  // Printed back verbatim in `wrote \u2026`, so it must be one plain line.
   if (/[\x00-\x1f\x7f]/.test(a.out)) throw new UsageError("--out must not contain control characters");
   if (!/\.(png|webp|html)$/i.test(a.out)) throw new UsageError("--out must end in .png, .webp or .html");
   return a;
@@ -193,9 +179,7 @@ async function main(): Promise<number> {
   return 0;
 }
 
-// Today's load, written to the status file and then printed. The write comes
-// first so that a run whose write failed prints its one-line error and nothing
-// else: a caller never reads a line that was not saved for the status line.
+// The write comes first: a caller never reads a line that was not saved.
 async function status(a: Args, now: Date): Promise<number> {
   const days: Day[] = await report({ projects: a.projects, to: a.to, days: a.days, now });
   const line = renderStatus(statusOf(days[0]!, now));

package/src/parse.ts

@@ -5,9 +5,8 @@ const INTERRUPT_PREFIX = "[Request interrupted by user";
 const REJECT_PREFIX = "The user doesn't want to proceed with this tool use";
 const QUESTION_TOOL = "AskUserQuestion";
 const PLAN_TOOL = "ExitPlanMode";
-// Inbound messages from subagents, other sessions and background tasks: the human
-// has to read and react to these, but did not type them, so they are `report`
-// events, never `prompt`. An interrupt marker is checked first and always wins.
+// Inbound agent messages: read and reacted to, but not typed, so `report`, never
+// `prompt`. An interrupt marker is checked first and wins.
 const AGENT_MARKERS = [
   "Another Claude session sent a message:",
   "<teammate-message",
@@ -20,10 +19,8 @@ type Rec = Record<string, unknown>;
 const isObj = (v: unknown): v is Rec => typeof v === "object" && v !== null;
 const str = (v: unknown): string | null => (typeof v === "string" ? v : null);
 
-// The text a marker is compared against: the content itself when it is a string,
-// otherwise the first `{type:"text"}` block anywhere in the array. A pasted
-// screenshot puts an `image` block in front of what the person typed, so the
-// text is not always the first block.
+// A pasted screenshot puts an `image` block before the typed text, so the text
+// block is searched for, not taken from content[0].
 const firstText = (content: unknown): string | null => {
   if (typeof content === "string") return content;
   if (!Array.isArray(content)) return null;
@@ -35,16 +32,12 @@ export function parseTranscript(text: string): Event[] {
   const events: Event[] = [];
   let lastTs: number | null = null;
   let lastMode: string | null = null;
-  // Mode switches seen before this file's first timestamped record, waiting for
-  // a time to belong to.
   let pendingModeChanges = 0;
-  // Dedupes `output` events by requestId within this one file: Claude Code
-  // writes one record per content block of a response, repeating the same
-  // requestId and usage, so only the first qualifying record counts.
+  // Claude Code writes one record per content block of a response, repeating
+  // the requestId and usage; only the first qualifying record counts.
   const seenRequestIds = new Set<string>();
-  // `tool_use` ids of the two tools whose result the human writes: the option
-  // they picked, or their verdict on a plan. Every other `tool_result` is the
-  // machine reporting back, so the pairing is what tells the two apart.
+  // Ids of the two tools whose result the human writes; every other
+  // `tool_result` is the machine reporting back.
   const askedIds = new Set<string>();
 
   for (const line of text.split("\n")) {
@@ -60,11 +53,8 @@ export function parseTranscript(text: string): Event[] {
     if (type === "permission-mode") {
       const m = str(rec.permissionMode);
       if (m === null) continue;
-      // The baseline mode is tracked as soon as it is seen, even before any
-      // timestamp exists, so a later switch away from it can be detected. A
-      // switch before any timestamp waits: switching the mode before typing
-      // anything is how a session often starts, and it is attributed to the
-      // first timestamped record that follows. A file with none drops them.
+      // A switch before the first timestamped record is how a session often
+      // starts; it waits and is attributed to that record.
       if (lastMode !== null && m !== lastMode) {
         if (lastTs === null) pendingModeChanges++;
         else events.push({ ts: lastTs, sessionId, kind: "mode_change" });
@@ -106,14 +96,9 @@ export function parseTranscript(text: string): Event[] {
         const id = str(b.id);
         if (id !== null) askedIds.add(id);
       }
-      // `output`: one event per distinct requestId per file, the first record seen
-      // that has a string requestId, numeric usage.output_tokens and at least one
-      // text block. A response holding only tool_use blocks is not text the human
-      // reads, so it never triggers this, even on its first (and only) record.
-      // A count only counts when it is one a token count can be: a finite
-      // non-negative integer. `1e309` parses to Infinity and a negative count
-      // to -Infinity, and a day holding both summed to NaN; such a record is
-      // still `activity`, it just carries no tokens.
+      // A response of only tool_use blocks is not text the human reads and carries
+      // no output tokens. A count must be a finite non-negative integer: `1e309`
+      // parses to Infinity, and a day once summed to NaN.
       const requestId = str(rec.requestId);
       const usage = isObj(rec.message) ? rec.message.usage : undefined;
       const outputTokens = isObj(usage) ? usage.output_tokens : undefined;

package/src/render.ts

@@ -1,4 +1,5 @@
 import { formatCount, plural } from "./format.ts";
+import { levelOf } from "./score.ts";
 import type { Day, HourBucket, Level } from "./types.ts";
 
 const GLYPH: Record<Level, string> = { Calm: "░", Warming: "▒", Heating: "▓", Fried: "█" };
@@ -11,9 +12,8 @@ const paint = (s: string, level: Level, color: boolean) => (color ? `\x1b[${ANSI
 const dim = (s: string, color: boolean) => (color ? `\x1b[2m${s}\x1b[0m` : s);
 const hm = (min: number) => `${Math.floor(min / 60)}h${String(min % 60).padStart(2, "0")}`;
 const hhmm = (d: Date) => `${String(d.getHours()).padStart(2, "0")}:${String(d.getMinutes()).padStart(2, "0")}`;
-// A window that includes today reads a transcript Claude Code is still appending
-// to; this line marks the snapshot time on the one day still open, so two runs
-// minutes apart are explained rather than silently disagreeing.
+// Marks the snapshot time on the open day, so two runs minutes apart are
+// explained rather than silently disagreeing.
 const snapshotLine = (d: Day | undefined, color: boolean): string[] =>
   d?.asOf ? [dim(`  as of ${hhmm(new Date(d.asOf))}, this hour is still running`, color)] : [];
 const label = (date: string) => {
@@ -22,14 +22,15 @@ const label = (date: string) => {
 };
 
 export function renderWeek(days: Day[], color: boolean): string {
-  // Geometry: 12-char label, 24 cells of 3 chars (glyph in the middle), peak in 6, active in 8. Header hours are `HH ` so they sit over the cells.
+  // 12-char label, 24 cells of 3 chars, peak in 6, active in 8.
   const header = "            " + Array.from({ length: 24 }, (_, h) => `${String(h).padStart(2, "0")} `).join("") + "  peak  active";
   const rows = days.map((d) => {
     const cells = d.buckets.map((b) => ` ${b.score ? paint(GLYPH[b.score.level], b.score.level, color) : "·"} `).join("");
-    return `${label(d.date).padEnd(12)}${cells}${String(d.peak ?? "-").padStart(6)}${hm(d.activeMin).padStart(8)}`;
+    // Padding stays outside the paint so the escape codes add no width.
+    const peak = d.peak === null ? "-".padStart(6) : " ".repeat(6 - String(d.peak).length) + paint(String(d.peak), levelOf(d.peak), color);
+    return `${label(d.date).padEnd(12)}${cells}${peak}${hm(d.activeMin).padStart(8)}`;
   });
-  // A painted glyph's own \x1b[0m would cancel the line's outer dim, so in
-  // color mode re-emit \x1b[2m right after it to keep the label dim too.
+  // A painted glyph's own \x1b[0m cancels the line's dim; re-emit it after.
   const dimGlyph = (level: Level) => paint(GLYPH[level], level, color) + (color ? "\x1b[2m" : "");
   const legend = dim("  " + LEVELS.map((l) => `${dimGlyph(l)} ${LEVEL_NAME[l]}`).join("   "), color);
   const active = days.reduce((s, d) => s + d.activeMin, 0);
@@ -37,18 +38,16 @@ export function renderWeek(days: Day[], color: boolean): string {
   const reports = days.reduce((s, d) => s + d.totals.reports, 0);
   const decisions = days.reduce((s, d) => s + d.totals.decisions, 0);
   const maxSessions = Math.max(0, ...days.map((d) => d.totals.maxSessions));
-  // Counts go through formatCount so a very active window (999 999 999 prompts) still
-  // fits inside the grid's 100 columns; hm(active) has no compact form, so it stays as is.
+  // Compact counts keep a very active window inside the grid's 100 columns.
   const totals = dim(`  ${hm(active)} active   ${plural(prompts, "prompt")}   ${plural(reports, "report")}   ${plural(decisions, "decision")}   ${plural(maxSessions, "session")} at once`, color);
   return [header, ...rows, "", legend, totals, ...snapshotLine(days[days.length - 1], color)].join("\n");
 }
 
-// Values at or above 1000 are shown as one decimal of a thousand (e.g. "41.2k"); smaller values print as-is.
 const fmtTokens = (n: number): string => (n >= 1000 ? `${(n / 1000).toFixed(1)}k` : String(n));
 
 type Col = [string, number, (b: HourBucket) => string];
 
-// Widths reproduce the header the test pins: hour is left-aligned, level is left-aligned inside a 9-wide cell with two leading spaces, everything else right-aligned.
+// Hour left-aligned, level left-aligned after two spaces, the rest right-aligned.
 const COLS: Col[] = [
   ["hour", 5, (b) => `${String(b.hour).padStart(2, "0")}:00`],
   ["index", 7, (b) => String(b.score?.index ?? "")],
@@ -73,10 +72,8 @@ const EXPLAIN: Col[] = [
   ["strk", 6, (b) => String(b.score?.parts.streak ?? "")],
   ["late", 6, (b) => String(b.score?.parts.late ?? "")],
 ];
-// Event columns: left out of the table for a day where every active bucket reads
-// zero (a quiet day is mostly zeros, and the eye hunts for the non-zero cell).
-// The skeleton columns (hour, index, level, sess, prompts, streak, out-tok, and
-// the six --explain parts) always show, so two days still line up.
+// Left out of the table for a day where every active bucket reads zero; the
+// other columns always show, so two days still line up.
 const EVENT_COLS = new Set(["rep", "intr", "rej", "quest", "plan", "mode", "ctx-sw"]);
 const FULL_NAME: Record<string, string> = {
   rep: "reports", intr: "interrupts", rej: "rejects", quest: "questions",
@@ -89,9 +86,8 @@ export function renderDay(day: Day, opts: { explain: boolean; color: boolean }):
     cells.map((c, i) => { const w = columns[i]![1]; if (i === 0) return c.padEnd(w); if (columns[i]![0] === "level") return `  ${c.padEnd(w - 2)}`; return c.padStart(w); }).join("").trimEnd();
 
   const active = day.buckets.filter((b) => b.score !== null);
-  // No active bucket: just the full header, plus the snapshot line if this
-  // quiet day is still open — otherwise a run at 09:00 and one at 18:00 on an
-  // empty today would print the identical line.
+  // The snapshot line still shows on an empty open day, or a run at 09:00 and
+  // one at 18:00 would print the identical line.
   if (active.length === 0) return [line(cols, cols.map(([name]) => name)), ...snapshotLine(day, opts.color)].join("\n");
 
   const visible = cols.filter(([name, , f]) => !EVENT_COLS.has(name) || active.some((b) => f(b) !== "0"));
@@ -101,8 +97,7 @@ export function renderDay(day: Day, opts: { explain: boolean; color: boolean }):
   const rows = active.map((b) => {
     const cells = visible.map(([, , f]) => f(b));
     const text = line(visible, cells);
-    // Safe only because no other column can contain a level word (Calm/Warming/Heating/Fried);
-    // if one ever could, this would need to target the level column's slice, not a string search.
+    // Safe only while no other column can contain a level word.
     return opts.color && b.score ? text.replace(b.score.level, paint(b.score.level, b.score.level, true)) : text;
   });
   const lines = [header, ...rows];

package/src/report.ts

@@ -6,7 +6,6 @@ import type { Day, Transcript } from "./types.ts";
 
 export type ReportOptions = { projects: string; to: string; days: number; now?: Date };
 
-// The shell's seam: lists and reads files, then hands the text to the pure core.
 export async function report(o: ReportOptions): Promise<Day[]> {
   const window = { to: o.to, days: o.days, now: o.now };
   const paths = await scan(o.projects, windowBounds(window).cutoffMs);

package/src/scan.ts

@@ -2,12 +2,9 @@ import type { Dirent } from "node:fs";
 import { open, readdir, stat } from "node:fs/promises";
 import { join } from "node:path";
 
-// Lists transcript files worth reading. Subagent transcripts live under a `subagents`
-// directory and are the parent agent's conversation, not the human's; mtime is checked
-// first, and for a file mtime would drop, the last timestamp in its tail decides.
+// A `subagents` directory holds the parent agent's conversation, not the human's.
 export async function scan(projects: string, cutoffMs: number): Promise<string[]> {
-  // No path in either message: it may be a value the user typed, or the
-  // homedir-derived default, and the CLI must never print a filesystem path.
+  // No path in either message: the CLI never prints one.
   let root;
   try {
     if (!(await stat(projects)).isDirectory()) throw new Error("not a directory");
@@ -22,9 +19,8 @@ export async function scan(projects: string, cutoffMs: number): Promise<string[]
   return out.sort();
 }
 
-// One directory at a time, so one unreadable directory or a symlink loop below the
-// root costs only that directory. A symlink is not followed into: Claude Code never
-// writes one, and following it is how a loop or a stray link to $HOME would get in.
+// One unreadable directory costs only itself. Symlinks are not followed: Claude
+// Code never writes one, and following one is how a loop or $HOME would get in.
 async function collect(dir: string, entries: Dirent[], cutoffMs: number, out: string[]): Promise<void> {
   for (const entry of entries) {
     const full = join(dir, entry.name);
@@ -41,12 +37,9 @@ async function collect(dir: string, entries: Dirent[], cutoffMs: number, out: st
   }
 }
 
-// mtime is a hint, not the truth: a transcript synced from another machine, restored by a
-// tool that rewrites times, or written under clock skew can be older by mtime than the
-// records inside it. For a file mtime would drop, the last "timestamp" in its final 64 KB
-// decides. 64 KB, not a few, because the last record of a conversation is often a big tool
-// result (a file read, grep output) and its own timestamp field sits in front of all that
-// text. The tail is matched for that one field and discarded; nothing else is read.
+// mtime can be older than the records inside (sync, restore, clock skew), so for
+// a file mtime would drop, the last "timestamp" in its final 64 KB decides. 64 KB
+// because the last record is often a big tool result with its timestamp in front.
 const TAIL_BYTES = 65_536;
 async function lastTimestampMs(path: string): Promise<number> {
   const fh = await open(path, "r");

package/src/score.ts

@@ -1,8 +1,7 @@
 import type { Level, Metrics, Parts, Score } from "./types.ts";
 
-// Calibration lives here and nowhere else. A change is one diff plus a CHANGELOG line.
-// Points of 100, kept as integers so 0.5 sums stay exact in floating point.
-// Norms are the p90 of two weeks of real data on two machines (see CHANGELOG).
+// Calibration lives here and nowhere else. Integer points of 100, so 0.5 sums
+// stay exact; norms are the p90 of two weeks on two machines (see CHANGELOG).
 export const WEIGHTS = { parallel: 25, pace: 15, supervision: 30, reading: 10, streak: 10, late: 10 } as const;
 export const NORMS = { parallelSpan: 4, pacePerHour: 20, supervisionPerHour: 45, decisionWeight: 3, readingTokens: 80_000, streakMin: 40 } as const;
 export const LEVELS: readonly { max: number; level: Level }[] = [
@@ -23,8 +22,7 @@ export function score(m: Metrics): Score | null {
   if (m.sessions === 0) return null;
   const parallel = clamp01((m.sessions - 1) / NORMS.parallelSpan);
   const pace = clamp01(m.prompts / NORMS.pacePerHour);
-  // Supervision is one load: an explicit decision costs `decisionWeight` times what
-  // reacting to one agent report or one session hop costs, and the three share a norm.
+  // A decision costs `decisionWeight` reports or session hops; the three share a norm.
   const supervision = clamp01(
     (NORMS.decisionWeight * m.decisions + m.reports + m.contextSwitches) / NORMS.supervisionPerHour,
   );
@@ -40,7 +38,7 @@ export function score(m: Metrics): Score | null {
     streak: WEIGHTS.streak * streak,
     late: WEIGHTS.late * late,
   };
-  // parts are the same raw weighted points, rounded to one decimal for display only.
+  // Rounded for display only.
   const parts: Parts = {
     parallel: Math.round(raw.parallel * 10) / 10,
     pace: Math.round(raw.pace * 10) / 10,
@@ -49,8 +47,7 @@ export function score(m: Metrics): Score | null {
     streak: Math.round(raw.streak * 10) / 10,
     late: Math.round(raw.late * 10) / 10,
   };
-  // index is rounded once, from the unrounded raw points, so per-component
-  // rounding (parts, above) can never tip it across a boundary raw didn't.
+  // Rounded once from the raw points, so parts' rounding can never tip it across a boundary.
   const index = Math.round(
     raw.parallel + raw.pace + raw.supervision + raw.reading + raw.streak + raw.late,
   );

package/src/status.ts

@@ -1,11 +1,7 @@
 import { GAP_MS } from "./derive.ts";
 import type { Day, Level } from "./types.ts";
 
-// The status file's content, as data: today's load reduced to the nine values a
-// status line needs. Core, not shell — this file never reads the clock, the
-// environment or the file system, and never writes one; `now` arrives as an
-// argument and `src/statusfile.ts` does the writing. The field order below is
-// the file format (see the status-file design spec) and JSON.stringify keeps it.
+// The status file's nine values. The field order is the file format.
 export type Status = {
   schema: 1;
   asOf: string;
@@ -18,34 +14,26 @@ export type Status = {
   streakMin: number;
 };
 
-// `hour` is the local hour containing `now`; index and level describe that
-// hour's bucket, peak and activeMin the whole day, and streakMin the streak the
-// person is in right now. A day the report did not mark as open has no asOf, so
-// `now` stands in and the function stays total.
-//
-// The live streak, not the bucket's: a status line answers "how long have I
-// been at this?", and the bucket's number drops to zero at every hour boundary
-// and stops growing between two actions. While the last action is no more than
-// GAP_MS behind `now`, the streak runs from its first action to `now`; once the
-// break is longer than that, it is over and reads 0.
+// index and level are the day's `live` bucket, not the hour's: an hour's bucket
+// is nearly empty just after the hour turns. streakMin is measured against `now`,
+// not the bucket's: it must not reset on the hour or stop between two actions,
+// and it is over once the last action is more than GAP_MS behind `now`.
 export function statusOf(day: Day, now: Date): Status {
   const hour = now.getHours();
-  const bucket = day.buckets[hour];
   const live = day.presence !== null && now.getTime() - Date.parse(day.presence.lastAt) <= GAP_MS;
   return {
     schema: 1,
     asOf: day.asOf ?? now.toISOString(),
     date: day.date,
     hour,
-    index: bucket?.score?.index ?? null,
-    level: bucket?.score?.level ?? null,
+    index: day.live?.score?.index ?? null,
+    level: day.live?.score?.level ?? null,
     peak: day.peak,
     activeMin: day.activeMin,
     streakMin: live ? Math.round((now.getTime() - Date.parse(day.presence!.streakStartAt)) / 60000) : 0,
   };
 }
 
-// One line of JSON, the fields in the order declared above, newline at the end.
 export function renderStatus(s: Status): string {
   return JSON.stringify(s) + "\n";
 }

package/src/statusfile.ts

@@ -1,41 +1,30 @@
-// The only module that writes the status file. Shell, not core: it owns the
-// path, the directory, the temporary file, the rename and the modes. The line
-// it is handed comes from the pure `src/status.ts`.
+// The only module that writes the status file.
 import { chmod, mkdir, open, rename, unlink } from "node:fs/promises";
 import { join } from "node:path";
 
 const FAILED = "cannot write the status file";
 
-// Write `line` to ~/.claude/zapara/status.json atomically: an exclusively
-// created temporary file in the same directory, then a rename over the target.
-// A reader sees the old file or the new one, never a partial line, and never a
-// file written through a symlink someone left at the target: `rename` replaces
-// the link. HOME comes from the env passed in rather than os.homedir(), so an
-// empty HOME is the error the spec names instead of a silent fallback.
+// Atomic: a temporary file in the same directory, then a rename over the
+// target, so a reader never sees a partial line and a symlink at the target is
+// replaced, not written through. HOME comes from `env`, not os.homedir(), so an
+// empty HOME is an error rather than a silent fallback.
 export async function writeStatus(line: string, env: NodeJS.ProcessEnv): Promise<void> {
   const home = env.HOME;
   if (!home) throw new Error(FAILED);
-  // The modes below are a request the umask narrows, so the umask becomes ours
-  // before anything is created: zapara is a short-lived CLI and the status file
-  // is the only thing it writes from here on. Setting it, rather than widening
-  // each path afterwards, is what makes `mkdir` and `open` come out exactly
-  // 0700 and 0600 on the first try — and it closes the window where one run has
-  // created `~/.claude` too narrow to enter and a second run, seeing a parent
-  // that already exists, fails inside it.
+  // The umask narrows the modes below; set it first so `mkdir` and `open` come
+  // out 0700 and 0600 on the first try, with no window where a second run finds
+  // a parent it cannot enter. Nothing else is written from here on.
   process.umask(0o077);
   const dir = join(home, ".claude", "zapara");
-  // The name is unique to this run: two detached runs may write at once, each
-  // renames its own complete file and the last rename wins. So this run opens
-  // its temp file with `wx` (an existing file or symlink at the name is an
-  // error, never followed) and never opens, reuses or deletes one it did not
-  // create — from the outside a crashed run's leftover and a slow run's file
-  // in flight look the same, and removing the second would break that promise.
+  // Unique per run: concurrent runs each rename their own complete file. Opened
+  // with `wx` so a file or symlink already at the name is an error, and never
+  // reused or deleted if not ours: a crashed run's leftover and a slow run's
+  // file in flight look the same from outside.
   const tmp = join(dir, `status.json.${process.pid}.${Math.random().toString(36).slice(2, 10)}.tmp`);
   let created = false;
   try {
     await mkdir(dir, { recursive: true, mode: 0o700 });
-    // `mkdir` leaves a directory that already exists exactly as it was, so a
-    // status directory someone else created loose is tightened here.
+    // `mkdir` leaves an existing directory as it was; tighten it.
     await chmod(dir, 0o700);
     const handle = await open(tmp, "wx", 0o600);
     created = true;
@@ -43,8 +32,6 @@ export async function writeStatus(line: string, env: NodeJS.ProcessEnv): Promise
     await chmod(tmp, 0o600);
     await rename(tmp, join(dir, "status.json"));
   } catch {
-    // Only this run's own file, and a failure to remove it changes nothing:
-    // the error below is what the caller acts on either way.
     if (created) await unlink(tmp).catch(() => {});
     throw new Error(FAILED);
   }

package/src/types.ts

@@ -10,12 +10,11 @@ export type Metrics = {
 export type Level = "Calm" | "Warming" | "Heating" | "Fried";
 export type Parts = { parallel: number; pace: number; supervision: number; reading: number; streak: number; late: number }; // weighted points, sum ≈ index
 export type Score = { index: number; level: Level; parts: Parts };
-export type HourBucket = Metrics & { hour: number; score: Score | null };
+export type LiveBucket = Metrics & { score: Score | null };
+export type HourBucket = LiveBucket & { hour: number };
 export type Totals = { prompts: number; reports: number; outputTokens: number; interrupts: number; rejects: number; questions: number; plans: number; modeSwitches: number; decisions: number; contextSwitches: number; maxSessions: number };
-// asOf is set only on the day that is still open when the report runs (the day
-// containing `now`), ISO 8601 UTC.
-// `presence` is the day's last human action and the start of the streak that
-// action belongs to, both ISO 8601 UTC. The start may lie on an earlier day or
-// in the look-back. `null` on a day with no human action. It is what lets a
-// reader measure the streak against its own clock instead of the hour bucket.
-export type Day = { date: string; peak: number | null; mean: number | null; activeMin: number; presence: { lastAt: string; streakStartAt: string } | null; totals: Totals; buckets: HourBucket[]; asOf?: string };
+// `asOf` and `live` exist only on the day containing `now`: `live` is the sixty
+// minutes `(asOf − 60 min, asOf]`, by the hour bucket's rule, look-back included.
+// `presence` is the day's last human action and the start of its streak, which
+// may lie on an earlier day; instants are ISO 8601 UTC.
+export type Day = { date: string; peak: number | null; mean: number | null; activeMin: number; presence: { lastAt: string; streakStartAt: string } | null; totals: Totals; buckets: HourBucket[]; asOf?: string; live?: LiveBucket };