@drakulavich/zapara 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to this project are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-09-22
+
+### Changed
+- The week grid dims a day no hour scored in, so a weekend recedes behind the
+  working days around it.
+
+## [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.
+A run that works exits 0, and so does a window with no data, which prints an empty grid. Exit 1 is a failure zapara can name, printed as one line to stderr that never contains 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. Exit 2 is a usage error, such as a bad date, an unknown flag or a value flag given twice; it prints one line and a hint to `--help`.
 
 ## 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. |
@@ -214,7 +214,7 @@ index = round(25*parallel + 15*pace + 30*supervision + 10*reading + 10*streak +
 | Heating | 60–84 |
 | Fried | 85–100 |
 
-The norms are the p90 of two weeks of real transcripts on two machines, 116 and 114 active hours. Why each one is what it is, and what surprised us in that data, is in [How the numbers are made](docs/how-the-numbers-are-made.md#5-the-index).
+The norms are the p90 of two weeks of real transcripts on two machines, 116 and 114 active hours. Why each one is what it is, and what surprised me in that data, is in [How the numbers are made](docs/how-the-numbers-are-made.md#5-the-index).
 
 Weights and norms live in one exported constant in `src/score.ts`, so a recalibration is one diff there plus a line in `CHANGELOG.md`.
 
@@ -258,6 +258,16 @@ 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
+## Where it comes from
 
-MIT. See [LICENSE](LICENSE).
+The question comes from Addy Osmani's [Your parallel Agent limit](https://addyosmani.com/blog/cognitive-parallel-agents/). More agents running does not make more of you available, because "your cognitive bandwidth doesn't parallelize", and the cost of the ones you are not looking at is what he calls the ambient anxiety tax: "the part of your mind that can't fully relax because it knows something might be silently going sideways in a thread you haven't checked in twenty minutes." His own ceiling is "somewhere around three to four threads depending on complexity", and his advice is to start with one thread less than feels right.
+
+The index was calibrated before I read that, from the 90th percentile of two weeks on two machines, and it arrived at the same number: `NORMS.parallelSpan` in [src/score.ts](src/score.ts) is 4, so the fifth session running at once spends all 25 points for parallel work.
+
+The post and this tool disagree about what to watch. Osmani's signal is the quality of your own review: you have passed your ceiling when your confidence in what you are accepting starts dropping. A transcript cannot see that. It can see how much model output went past you, which is the `out-tok` column and ten of the hundred points, and it can see the shape of the hour around it. The index is a proxy with a known blind spot, and the number is worth something only next to your memory of the hour it scores.
+
+Most of the advice in this area stops at fewer threads, smaller scope and more breaks, with few numbers you can hold yourself to. An hour with a score on it is at least something you can disagree with.
+
+---
+
+<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.6.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,18 @@ 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);
+    const row = `${label(d.date).padEnd(12)}${cells}${peak}${hm(d.activeMin).padStart(8)}`;
+    // A day no hour scored in is 24 dots and a dash: no escape of its own, so
+    // one dim wrapper is enough.
+    return d.peak === null ? dim(row, color) : row;
   });
-  // 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 +41,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 +75,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 +89,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 +100,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 };