@drakulavich/zapara 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to this project are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-09-21
+
+### Changed
+- Streak norm recalibrated for the presence rule: 40 minutes of your own uninterrupted actions now score the full streak points (was 120, the p90 of the old rule that let agent activity keep a streak alive; the p90 under the new rule is 33 on one machine and 48 on another, and 40 sits between them).
+- Presence counts every human action, not only prompts: an interrupt, a tool rejection and an answer to a question or a plan hold a streak open and fill active minutes the same way a prompt does. They remain decisions where they already were; nothing is counted twice.
+- An hour's streak is the longest streak seen in it, not the one it happened to end on. A single prompt after a break no longer erases the run the hour held, nor the streak points of that hour's index.
+- The status file's streak is live: it counts from the first action of the streak you are in up to `asOf`, and resets to `0` once you have been away for more than ten minutes. Before, it was the current hour's bucket, so it fell to zero at every hour boundary.
+- `Day.presence` in `--json`: the day's last human action and the start of the streak it belongs to, as instants, or `null` on a day with no action of yours.
+
+### Fixed
+- The card's longest streak is no longer under-reported: a run that ended in an hour where another began used to be measured only up to the end of the hour before.
+- The status line's streak no longer drops to zero at each hour boundary.
+- `card --out` into a directory that does not exist or refuses the write says `cannot write the card: check the --out directory` instead of printing the full path back in a file-system error.
+- A permission-mode switch made before the first message of a session counts: it is attributed to the first timestamped record that follows, instead of vanishing.
+- A transcript whose modification time is outside the window is read when its last record is a big one: the rescue that looks for the last timestamp reads 64 KB from the end instead of 4 KB, so a day that ended on a large tool result is no longer dropped in full.
+- An output-token count that is not a finite non-negative integer is ignored instead of poisoning the day: a corrupt transcript could put `NaN` in the token column and `null` in the JSON, beside a made-up level.
+- A prompt with a pasted screenshot counts again: the image block comes before the typed text, and such prompts were read as no text at all, so a day spent pasting screenshots showed no prompts and no active minutes.
+
+## [0.3.1] - 2026-09-19
+
+### Changed
+- Streak and active minutes count your presence, not the agent's: a streak is your prompts no more than 10 minutes apart across sessions, and active minutes are the five-minute slots those streaks cover. Agent work while you are away no longer keeps a streak alive or fills the day.
+
 ## [0.3.0] - 2026-09-19
 
 ### Added

package/README.md

@@ -12,75 +12,88 @@
   <img src="https://raw.githubusercontent.com/drakulavich/zapara/main/assets/demo.webp" alt="zapara demo: week heatmap, day table, JSON" width="800">
 </p>
 
-Claude Code writes a JSONL transcript for every session under `~/.claude/projects`. zapara reads those files, puts each record in the local hour it happened in, and turns the hour into one number. A week is a heatmap of seven rows by 24 cells; a day is a table with one row per hour and, with `--explain`, the weighted contribution of each component. Nothing is installed into Claude Code, no hook is registered, and no network call is made.
+Claude Code writes a JSONL transcript for every session under `~/.claude/projects`. zapara reads those files, puts each record in the local hour it happened in, and turns the hour into one number. A week is a heatmap of seven rows by 24 cells; a day is a table with one row per hour and, with `--explain`, the weighted contribution of each component.
 
-## Quick Start
+## Quick start
 
 ```bash
-# Install Bun if you do not have it (zapara needs 1.4 or newer)
+# Skip this if you already have Bun 1.4 or newer
 curl -fsSL https://bun.sh/install | bash
 
-# The last 7 days, straight from the registry
+# Run it once, without installing
 bunx @drakulavich/zapara@latest
+```
+
+To keep it, install it with Bun. The same command upgrades it later.
+
+```bash
+bun add -g @drakulavich/zapara
+```
 
-# Yesterday, hour by hour, with the components behind each index
-bunx @drakulavich/zapara@latest yesterday --explain
+`zapara` lands in Bun's global bin directory, `~/.bun/bin` unless `BUN_INSTALL_BIN` says otherwise; `bun pm bin -g` prints the one in force. Bun's own installer puts that directory on your PATH; a Homebrew Bun does not, so add it yourself. Then:
 
-# The card
-bunx @drakulavich/zapara@latest card
+```bash
+zapara                      # the last 7 days
+zapara yesterday --explain  # one day, with the components behind each index
+zapara card                 # the picture
 ```
 
-To keep it around, `bun add -g @drakulavich/zapara` puts `zapara` on your PATH. There is no build step and no runtime dependency: Bun runs `src/index.ts` from the package as it is.
+No build step and no runtime dependency: Bun runs `src/index.ts` from the package as it is.
 
 ## What it looks like
 
-Both pictures below come from the synthetic fixture in `tests/fixtures/busy-week`: a calm morning of one session, a five-session storm in the middle of the day, and a late tail that runs past midnight.
+The week below, and the day behind the fold under it, come from the synthetic fixture in `tests/fixtures/busy-week`: a calm morning of one session, a five-session storm in the middle of the day, and a late tail that runs past midnight.
 
 ```
             00 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20 21 22 23   peak  active
-Mon 14/09    ·  ·  ·  ·  ·  ·  ·  ·  ·  ░  ░  ░  █  █  █  ·  ·  ·  ·  ·  ░  ░  ·  ░     87    6h00
-Tue 15/09    ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ░  ░  ░  ░  ▒  ▒  ▒  ░  ·  ·  ·  ·  ·  ·     33    4h00
+Mon 14/09    ·  ·  ·  ·  ·  ·  ·  ·  ·  ░  ░  ░  █  █  █  ·  ·  ·  ·  ·  ░  ░  ·  ░     87    8h50
+Tue 15/09    ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ░  ░  ░  ░  ▒  ▒  ▒  ░  ·  ·  ·  ·  ·  ·     33    7h55
 Wed 16/09    ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·      -    0h00
-Thu 17/09    ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ░  ░  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·     14    1h00
-Fri 18/09    ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ▓  ·  ·  ·  ·  ·  ·  ·  ·     82    1h00
-Sat 19/09    ░  ░  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·     24    1h00
+Thu 17/09    ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ░  ░  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·     15    1h55
+Fri 18/09    ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ▓  ·  ·  ·  ·  ·  ·  ·  ·     81    0h35
+Sat 19/09    ░  ░  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·     25    1h55
 Sun 20/09    ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·      -    0h00
 
   ░ calm   ▒ warming   ▓ heating   █ fried
-  13h00 active   346 prompts   0 reports   100 decisions   5 sessions at once
-```
-
-```
-hour   index  level    sess  prompts  intr  rej  quest  plan  mode  ctx-sw  streak  out-tok  par  pace   sup  read  strk  late
-09:00      9  Calm        1        6     0    0      0     0     0       0     53m      600    0   4.5     0   0.1   4.4     0
-10:00     14  Calm        1        6     0    0      0     0     0       0    113m      600    0   4.5     0   0.1   9.4     0
-11:00     15  Calm        1        6     0    0      0     0     0       0    173m      600    0   4.5     0   0.1    10     0
-12:00     87  Fried       5       55    20    1      1     1     2      54    237m    55.0k   25    15    30   6.9    10     0
-13:00     87  Fried       5       55    20    1      1     1     2      54    297m    55.0k   25    15    30   6.9    10     0
-14:00     87  Fried       5       55    20    1      1     1     2      54    357m    55.0k   25    15    30   6.9    10     0
-20:00      9  Calm        1        6     0    0      0     0     0       0     53m      600    0   4.5     0   0.1   4.4     0
-21:00     14  Calm        1        6     0    0      0     0     0       0    113m      600    0   4.5     0   0.1   9.4     0
-23:00     19  Calm        1        6     0    0      0     0     0       0     53m      600    0   4.5     0   0.1   4.4    10
-  no reports today
+  21h10 active   323 prompts   0 reports   86 decisions   5 sessions at once
 ```
 
 <details>
-<summary><b>Reproduce these pictures from the repository</b></summary>
+<summary><b>Monday hour by hour, and the commands that print both</b></summary>
 
-Two commands in a terminal reproduce them. The fixture's timestamps are UTC and zapara buckets by local time, so pin the zone to get these exact hours:
+The fixture's timestamps are UTC and zapara buckets by local time, so pin the zone to get these exact hours:
 
 ```bash
 TZ=UTC bun src/index.ts --projects tests/fixtures/busy-week --to 2026-09-20 --no-color
+```
+
+That prints the grid above. One day of it, with the weighted parts behind each index:
+
+```bash
 TZ=UTC bun src/index.ts 2026-09-14 --projects tests/fixtures/busy-week --explain --no-color
 ```
 
+```
+hour   index  level    sess  prompts  intr  rej  quest  plan  mode  ctx-sw  streak  out-tok  par  pace   sup  read  strk  late
+09:00     15  Calm        1        6     0    0      0     0     0       0     50m      600    0   4.5     0   0.1    10     0
+10:00     15  Calm        1        6     0    0      0     0     0       0    110m      600    0   4.5     0   0.1    10     0
+11:00     15  Calm        1        7     0    0      0     0     0       0    179m      600    0   5.3     0   0.1    10     0
+12:00     87  Fried       5       55    20    1      1     1     2      54    235m    55.0k   25    15    30   6.9    10     0
+13:00     87  Fried       5       55    20    1      1     1     2      54    295m    55.0k   25    15    30   6.9    10     0
+14:00     87  Fried       5       55    20    1      1     1     2      54    355m    55.0k   25    15    30   6.9    10     0
+20:00     15  Calm        1        6     0    0      0     0     0       0     50m      600    0   4.5     0   0.1    10     0
+21:00     15  Calm        1        6     0    0      0     0     0       0    110m      600    0   4.5     0   0.1    10     0
+23:00     25  Calm        1        6     0    0      0     0     0       0     50m      600    0   4.5     0   0.1    10    10
+  no reports today
+```
+
 The grid is a fixed 98 columns wide, 100 with its hour header, and does not reflow, so it needs a terminal at least that wide.
 
 </details>
 
 ## Share a card
 
-`zapara card` turns your last two weeks into one picture: a character named after the kind of load that dominates your hours, the sentence behind it, the peak hour, the share of calm, warming, heating and fried hours, and three highlights. No dates, no hour totals, nothing that reads as a timesheet.
+`zapara card` turns your last two weeks into one picture: a character named after the kind of load that dominates your hours, the sentence behind it, the peak hour, the share of calm, warming, heating and fried hours, and three highlights. It carries no dates and no hour totals, so it does not read as a timesheet.
 
 ```bash
 zapara card                    # writes zapara-card.png in the current directory
@@ -100,7 +113,7 @@ wrote zapara-card.png
 
 <p align="center"><img src="https://raw.githubusercontent.com/drakulavich/zapara/main/assets/card.webp" alt="zapara card: The Marathoner, longest streak 7h53m, 68% of hours calm" width="800"></p>
 
-This one comes from the same `busy-week` fixture as the pictures above. The picture is taken by a headless browser that Bun drives: WebKit on macOS, an installed Google Chrome elsewhere, so on Linux or Windows install Chrome, or write `--out card.html` and open the page in any browser.
+This one comes from the same `busy-week` fixture as the pictures above. A headless browser that Bun drives takes the picture: WebKit on macOS, an installed Google Chrome elsewhere. On Linux or Windows, install Chrome or write `--out card.html` and open the page in any browser.
 
 ## Usage
 
@@ -128,13 +141,13 @@ This one comes from the same `busy-week` fixture as the pictures above. The pict
 
 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; there is no flag to force text in a pipe yet. `card` always writes its file and prints its two lines, piped or not, and only `card --json` prints JSON. `status` always writes its file and prints the same JSON line, piped or not, and `--json` changes nothing there.
+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, or when `status` cannot write its file (three different messages, none with a path), and 2 for a usage error such as a bad date or an unknown flag, which prints one line and a hint to `--help`. A value flag given twice is a usage error. A window with no data prints an empty grid and exits 0.
+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.
 
 ## Status line
 
-A status line wants one number every thirty seconds and cannot wait half a second for a transcript scan, so zapara writes the number down and the status line reads it back. `zapara status` computes today exactly as `zapara today` does, writes it as one line of JSON to `~/.claude/zapara/status.json`, and prints the same line. Only `--projects` applies to it; the window flags, `--explain` and `--out` are usage errors, and `--json` changes nothing because the output is already JSON. There is one file per user, whatever `--projects` said, created with mode `0600` in a directory with mode `0700`; the write goes to a temporary file and is renamed into place, so a reader sees the old line or the new one and never half of one. The file holds the nine values below and nothing else: no path, no project, no session count, no text.
+A status line wants one number every thirty seconds and cannot wait half a second for a transcript scan, so zapara writes the number down and the status line reads it back. `zapara status` computes today exactly as `zapara today` does, writes it as one line of JSON to `~/.claude/zapara/status.json`, and prints the same line. Only `--projects` applies; the window flags, `--explain` and `--out` are usage errors. There is one file per user, whatever `--projects` said, created with mode `0600` in a directory with mode `0700`; the write goes to a temporary file and is renamed into place, so a reader sees the old line or the new one and never half of one. The file holds the nine values below and nothing else: no path, no project, no session count, no text.
 
 ```json
 {"schema":1,"asOf":"2026-09-19T12:30:38.300Z","date":"2026-09-19","hour":15,"index":36,"level":"Warming","peak":41,"activeMin":555,"streakMin":166}
@@ -142,31 +155,31 @@ A status line wants one number every thirty seconds and cannot wait half a secon
 
 | Field | Meaning |
 |---|---|
-| `schema` | The shape of this file: `1`. A reader that sees a number it does not know shows nothing. It changes only when a field changes meaning or goes away; adding a field does not bump it. |
+| `schema` | The shape of this file: `1`. A reader that sees a number it does not know shows nothing. It changes only when a field changes meaning or goes away; adding a field does not bump it. A field that keeps its name, unit and range but is measured differently (the presence rule of 2026-09-19 for `activeMin` and `streakMin`) does not bump it either: a reader shows the corrected number, and the change is a CHANGELOG entry. |
 | `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. |
 | `peak` | The day's peak index so far, or `null` on a day with no activity. |
-| `activeMin` | Active minutes in the day so far; `0` on a day with no activity. |
-| `streakMin` | Minutes of the unbroken streak as of the current hour, `0` when there is none. |
+| `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. |
 
-Refreshing is the reader's job, and zapara adds no hook, no timer and no daemon. A reader decodes the file strictly and treats anything that fails validation, and a missing or unreadable file, as no data: it draws nothing and counts the file as stale. When the snapshot is stale or missing it starts `zapara status` as a detached process, does not wait for it, and draws what it has, which is also how the file first comes to exist on a machine that never ran zapara. It starts at most one run per threshold and never one per render, so a file that never validates costs one run per threshold and no more; the whole contract is in [the status file spec](docs/superpowers/specs/2026-09-19-zapara-status-file-design.md), and [pult](https://github.com/drakulavich/pult) is the reader that exists, with a five-minute threshold.
+Refreshing is the reader's job, and zapara adds no hook, no timer and no daemon. A reader that finds the file stale or missing starts `zapara status` detached and draws what it has, which is also how the file first comes to exist on a machine that never ran zapara. The rest of the contract, from strict decoding to concurrent runs, is in [the status file spec](docs/superpowers/specs/2026-09-19-zapara-status-file-design.md); [pult](https://github.com/drakulavich/pult) is the reader that exists, with a five-minute threshold.
 
 ## Privacy
 
-zapara reads `~/.claude/projects/**/*.jsonl`, skipping subagent transcripts under `subagents/`. Selection is by modification time first, and a file whose modification time is older than the window is opened only to read the last timestamp in its final 4 KB; nothing from that tail is kept or printed. Message text is compared against a few fixed markers, for interrupts, tool rejections and inbound agent messages, and then discarded. What survives into an event is a timestamp, a session id, an event kind and a token count.
+zapara reads `~/.claude/projects/**/*.jsonl`, skipping subagent transcripts under `subagents/`. It picks files by modification time first, and opens one whose modification time is older than the window only to read the last timestamp in its final 64 KB; nothing from that tail is kept or printed. It compares message text against a few fixed markers, for interrupts, tool rejections and inbound agent messages, then discards it. What survives into an event is a timestamp, a session id, an event kind and a token count.
 
-No message text, prompt length, file path or session title is kept, written or printed. The CLI never prints a path it derived or read, not even the projects root when it cannot open it. Nothing is sent anywhere, no file is written except the card or the status file you ask for, and nothing is installed into Claude Code.
+zapara keeps, writes and prints no message text, prompt length, file path or session title. The CLI never prints a path it derived or read, not even the projects root when it cannot open it. It sends nothing anywhere, writes no file except the card or the status file you ask for, and installs nothing into Claude Code.
 
 ## Limits
 
-- Time is local and buckets are whole hours, so an hour that straddles midnight or a daylight-saving change is bucketed by the local clock. On a fall-back day two wall-clock hours share one label and merge.
-- Only Claude Code transcripts are read. Work in other tools, and time away from the keyboard, is invisible.
-- Files are chosen by modification time, and a file whose modification time is older than the window is still read when the last timestamp in it falls inside the window, so a restored or synced transcript is not lost. A very old session touched today is read in full, but only its in-window events count.
+- Time is local and buckets are whole hours, so an hour that straddles midnight or a daylight-saving change is bucketed by the local clock. On a fall-back day two wall-clock hours share one label and merge, so that bucket can hold up to 120 active minutes and the day up to 1500.
+- zapara reads only Claude Code transcripts. Work in other tools, and time away from the keyboard, is invisible.
+- A file whose modification time is older than the window is still read when the last timestamp in it falls inside the window, so a restored or synced transcript is not lost. A very old session touched today is read in full, but only its in-window events count.
 - The transcript format is Claude Code's private format, built against version 2.1.274, and it may drift. `bun run stats` shows when it has.
-- The norms come from two machines of one user working in auto mode. They are a starting point for a conversation about the metric, not a study.
+- The norms come from two machines of one user working in auto mode, which makes them a starting point for a conversation about the metric rather than a study.
 - The 98-column grid does not adapt to a narrow terminal.
 - For the grid and the day a pipe always gets JSON, and there is no flag to ask for text instead.
 - The card needs a browser engine: WebKit comes with macOS, elsewhere Google Chrome must be installed. `--out card.html` works everywhere.
@@ -174,7 +187,7 @@ No message text, prompt length, file path or session title is kept, written or p
 
 ## Under the hood
 
-The formula behind the number and the transcript record behind every column, for when the number surprises you.
+The formula behind the number and the transcript record behind every column, for when the number surprises you. For the whole path from a transcript line to the status line, with a diagram, read [How the numbers are made](docs/how-the-numbers-are-made.md).
 
 <details>
 <summary><b>How the index works</b></summary>
@@ -186,7 +199,7 @@ parallel    = clamp((sessions - 1) / 4)                                   # 1 se
 pace        = clamp(prompts / 20)                                         # 10 prompts/hour → 0.5, 20+ → 1
 supervision = clamp((3 * decisions + reports + contextSwitches) / 45)     # 15 decisions alone → 1; 45 reports alone → 1
 reading     = clamp(outputTokens / 80000)                                 # 40k → 0.5, 80k+ → 1
-streak      = clamp(streakMin / 120)                                      # 60 min → 0.5, 2h+ → 1
+streak      = clamp(streakMin / 40)                                       # 20 min → 0.5, 40+ → 1
 late        = lateNight ? 1 : 0
 
 index = round(25*parallel + 15*pace + 30*supervision + 10*reading + 10*streak + 10*late)
@@ -201,7 +214,7 @@ index = round(25*parallel + 15*pace + 30*supervision + 10*reading + 10*streak +
 | Heating | 60–84 |
 | Fried | 85–100 |
 
-The norms come from two machines, 14 days each, of real transcripts covering 116 and 114 active hours. The surprise in that data was how rare explicit decisions are: in auto mode the p90 is 3 decisions per hour, so a component built on decisions alone reads near zero on hours that felt heavy. What those hours actually cost is reading the reports agents send back, switching between sessions, and getting through the volume of model output, which is why supervision carries 30 points and reading 10. Human prompts reached a p90 of 13 per hour on one machine and 20 on the other, hence the pace norm of 20. The parallel-session threshold follows the research this project started from rather than the transcripts: BCG and HBR report that productivity drops past three simultaneous AI tools, and Osmani makes the same point as three focused teammates beating five scattered ones.
+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).
 
 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`.
 
@@ -221,7 +234,7 @@ Weights and norms live in one exported constant in `src/score.ts`, so a recalibr
 | `plan` | `ExitPlanMode` tool calls in an assistant message, one per block. |
 | `mode` | Permission-mode switches. A `permission-mode` record whose mode differs from the previous one; the first record of a session sets the baseline and repeats of the same mode count nothing. |
 | `ctx-sw` | Context switches. Over the hour's prompts in time order, the number of consecutive pairs that came from different sessions. |
-| `streak` | Minutes since the current activity streak began, which may reach back before the hour. A gap longer than 10 minutes between records breaks the streak. |
+| `streak` | Minutes of the longest presence streak the hour saw. Presence is every action you take: a prompt, an interrupt, a tool rejection, an answer to a question or a plan. A streak is a run of them no more than 10 minutes apart, across sessions, and it may reach back before the hour. Agent activity between two of your actions does not bridge a gap. |
 | `out-tok` | Assistant output tokens, summed once per request and only for requests that produced a text block. Claude Code repeats the same usage on each content block of a response, and a request holding only tool calls is not text anyone reads. |
 
 `bun run stats --days 14` is the tool the norms were set with. It prints the per-hour distribution of each signal over the active hours of a window (n, p50, p75, p90, max, and how many hours were zero), the top hours by reports and by human prompts, and a format-drift line comparing records seen against events the parser recognised. Run it on another machine, or after a Claude Code update, to see whether the norms and the parser still fit. It prints numbers and nothing else.
@@ -237,7 +250,7 @@ bun install
 bun link
 ```
 
-`bun link` registers the clone's `bin` entry, so `zapara` runs this checkout; without it, `bun src/index.ts week` does the same thing.
+`bun link` registers the clone's `bin` entry, so `zapara` runs this checkout; without it, `bun src/index.ts` does the same thing.
 
 ```bash
 bun run check    # tsc --noEmit, then the test suite under TZ=UTC

package/package.json

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

package/src/derive.ts

@@ -1,5 +1,5 @@
 import { score } from "./score.ts";
-import type { Day, Event, HourBucket, Metrics, Totals, Window } from "./types.ts";
+import type { Day, Event, EventKind, HourBucket, Metrics, Totals, Window } from "./types.ts";
 
 export const LOOKBACK_MS = 3 * 60 * 60 * 1000;
 export const GAP_MS = 10 * 60 * 1000;
@@ -30,13 +30,26 @@ const emptyMetrics = (): Metrics => ({
   decisions: 0, contextSwitches: 0, activeMin: 0, streakMin: 0, lateNight: false,
 });
 
-type Acc = { m: Metrics; sessions: Set<string>; slots: Set<number>; lastPromptSession: string | null; lastActivity: { ts: number; streakStart: number } | null };
+// 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.
+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 };
 
 // Walks the sorted, look-back-filtered events once, keyed by "date|hour",
-// tracking the running activity streak (which may start before startMs) and
-// accumulating each bucket's raw counts. Events before startMs update the
-// streak only; they are never attributed to a bucket.
-function foldEvents(sorted: Event[], startMs: number): Map<string, Acc> {
+// 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.
+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 => {
     const d = new Date(ts);
@@ -44,24 +57,45 @@ function foldEvents(sorted: Event[], startMs: number): 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, lastActivity: null }; acc.set(k, a); }
+    if (!a) { a = { m: emptyMetrics(), sessions: new Set(), slots: new Set(), lastPromptSession: null, maxStreakMs: 0, lastPresence: null }; acc.set(k, a); }
     return a;
   };
 
-  let prevActivityTs: number | null = null;
-  let streakStart: number | null = null;
+  let prevPresenceTs: number | null = null;
+  let streakStart = 0; // always set by the first presence event, which starts a streak
+  let carried: { ts: number; streakStart: number } | null = null;
   for (const e of sorted) {
-    if (e.kind === "activity") {
-      streakStart = prevActivityTs === null || e.ts - prevActivityTs > GAP_MS ? e.ts : streakStart;
-      prevActivityTs = e.ts;
+    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 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.
+      if (e.ts < startMs) carried = { ts: e.ts, streakStart };
     }
-    if (e.ts < startMs) continue; // look-back: streak bookkeeping only
+    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.
+    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);
-        a.slots.add(Math.floor(e.ts / SLOT_MS));
-        a.lastActivity = { ts: e.ts, streakStart: streakStart! };
         break;
       case "prompt":
         a.m.prompts++;
@@ -77,20 +111,24 @@ function foldEvents(sorted: Event[], startMs: number): Map<string, Acc> {
       case "mode_change": a.m.modeSwitches++; break;
     }
   }
-  return acc;
+  return { acc, carried };
 }
 
 // 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.
+  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 = a.lastActivity ? Math.round((a.lastActivity.ts - a.lastActivity.streakStart) / 60000) : 0;
+      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,
@@ -112,6 +150,7 @@ function buildDay(date: string, acc: Map<string, Acc>): Day {
     peak: scored.length ? Math.max(...scored.map((b) => b.score!.index)) : null,
     mean: scored.length ? Math.round(scored.reduce((s, b) => s + b.score!.index, 0) / scored.length) : null,
     activeMin: buckets.reduce((s, b) => s + b.activeMin, 0),
+    presence: lastPresence && { lastAt: new Date(lastPresence.ts).toISOString(), streakStartAt: new Date(lastPresence.streakStart).toISOString() },
     totals,
     buckets,
   };
@@ -124,8 +163,16 @@ export function derive(events: Event[], w: Window): Day[] {
     .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);
-  const acc = foldEvents(sorted, startMs);
+  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.
+  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();

package/src/image.ts

@@ -23,6 +23,7 @@ export async function loadAssets(): Promise<CardAssets> {
 
 const BACKEND = process.platform === "darwin" ? "webkit" : "chrome";
 const ENGINE_LINE = "card needs a browser engine: install Google Chrome, or write --out card.html";
+const WRITE_LINE = "cannot write the card: check the --out directory";
 const WIDTH = 2400;
 const HEIGHT = 1260;
 const READY = 'document.fonts.ready.then(() => document.fonts.status === "loaded" && Array.from(document.images).every((i) => i.complete))';
@@ -32,12 +33,13 @@ const READY = 'document.fonts.ready.then(() => document.fonts.status === "loaded
 // 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. `writeFile` failures are the one
-// exception, left unmapped, so they keep reporting the user's own `--out` string.
+// 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.
 export async function renderCard(html: string, out: string, timeoutMs = 15_000): Promise<void> {
   const lower = out.toLowerCase();
   if (lower.endsWith(".html")) {
-    await writeFile(out, html);
+    await write(out, html);
     return;
   }
   let bytes: Uint8Array;
@@ -66,5 +68,15 @@ export async function renderCard(html: string, out: string, timeoutMs = 15_000):
   } finally {
     clearTimeout(timer!);
   }
-  await writeFile(out, bytes);
+  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.
+async function write(out: string, data: string | Uint8Array): Promise<void> {
+  try {
+    await writeFile(out, data);
+  } catch {
+    throw new Error(WRITE_LINE);
+  }
 }

package/src/parse.ts

@@ -20,9 +20,14 @@ 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.
 const firstText = (content: unknown): string | null => {
   if (typeof content === "string") return content;
-  if (Array.isArray(content) && isObj(content[0]) && content[0].type === "text") return str(content[0].text);
+  if (!Array.isArray(content)) return null;
+  for (const b of content) if (isObj(b) && b.type === "text") return str(b.text);
   return null;
 };
 
@@ -30,10 +35,17 @@ 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.
   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.
+  const askedIds = new Set<string>();
 
   for (const line of text.split("\n")) {
     if (line.trim() === "") continue;
@@ -50,10 +62,12 @@ export function parseTranscript(text: string): Event[] {
       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 is only ever emitted as an event once a timestamp is known;
-      // a switch that happens before any timestamp is known is dropped.
-      if (lastMode !== null && m !== lastMode && lastTs !== null) {
-        events.push({ ts: lastTs, sessionId, kind: "mode_change" });
+      // 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.
+      if (lastMode !== null && m !== lastMode) {
+        if (lastTs === null) pendingModeChanges++;
+        else events.push({ ts: lastTs, sessionId, kind: "mode_change" });
       }
       lastMode = m;
       continue;
@@ -64,6 +78,7 @@ export function parseTranscript(text: string): Event[] {
     if (Number.isNaN(ts)) continue;
     lastTs = ts;
     events.push({ ts, sessionId, kind: "activity" });
+    for (; pendingModeChanges > 0; pendingModeChanges--) events.push({ ts, sessionId, kind: "mode_change" });
 
     const content = isObj(rec.message) ? rec.message.content : undefined;
     if (type === "user") {
@@ -72,6 +87,8 @@ export function parseTranscript(text: string): Event[] {
         if (!isObj(b) || b.type !== "tool_result") continue;
         const t = firstText(b.content);
         if (t !== null && t.startsWith(REJECT_PREFIX)) events.push({ ts, sessionId, kind: "reject" });
+        const toolUseId = str(b.tool_use_id);
+        if (toolUseId !== null && askedIds.has(toolUseId)) events.push({ ts, sessionId, kind: "answer" });
       }
       const head = firstText(content);
       if (head === null) continue;
@@ -84,20 +101,27 @@ export function parseTranscript(text: string): Event[] {
       const blocks = Array.isArray(content) ? content : [];
       for (const b of blocks) {
         if (!isObj(b) || b.type !== "tool_use") continue;
-        if (b.name === QUESTION_TOOL) events.push({ ts, sessionId, kind: "question" });
-        else if (b.name === PLAN_TOOL) events.push({ ts, sessionId, kind: "plan_review" });
+        if (b.name !== QUESTION_TOOL && b.name !== PLAN_TOOL) continue;
+        events.push({ ts, sessionId, kind: b.name === QUESTION_TOOL ? "question" : "plan_review" });
+        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.
       const requestId = str(rec.requestId);
       const usage = isObj(rec.message) ? rec.message.usage : undefined;
       const outputTokens = isObj(usage) ? usage.output_tokens : undefined;
+      const tokens = typeof outputTokens === "number" && Number.isSafeInteger(outputTokens) && outputTokens >= 0 ? outputTokens : null;
       const hasText = blocks.some((b) => isObj(b) && b.type === "text");
-      if (requestId !== null && typeof outputTokens === "number" && hasText && !seenRequestIds.has(requestId)) {
+      if (requestId !== null && tokens !== null && hasText && !seenRequestIds.has(requestId)) {
         seenRequestIds.add(requestId);
-        events.push({ ts, sessionId, kind: "output", tokens: outputTokens });
+        events.push({ ts, sessionId, kind: "output", tokens });
       }
     }
   }

package/src/scan.ts

@@ -43,9 +43,11 @@ 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 4 KB
-// decides. The tail is matched for that one field and discarded; nothing else is read.
-const TAIL_BYTES = 4096;
+// 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.
+const TAIL_BYTES = 65_536;
 async function lastTimestampMs(path: string): Promise<number> {
   const fh = await open(path, "r");
   try {

package/src/score.ts

@@ -4,7 +4,7 @@ import type { Level, Metrics, Parts, Score } from "./types.ts";
 // 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).
 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: 120 } 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 }[] = [
   { max: 29, level: "Calm" },
   { max: 59, level: "Warming" },

package/src/status.ts

@@ -1,3 +1,4 @@
+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
@@ -17,12 +18,20 @@ export type Status = {
   streakMin: number;
 };
 
-// `hour` is the local hour containing `now`; index, level and streakMin describe
-// that hour's bucket, peak and activeMin the whole day. A day the report did not
-// mark as open has no asOf, so `now` stands in and the function stays total.
+// `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.
 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(),
@@ -32,7 +41,7 @@ export function statusOf(day: Day, now: Date): Status {
     level: bucket?.score?.level ?? null,
     peak: day.peak,
     activeMin: day.activeMin,
-    streakMin: bucket?.streakMin ?? 0,
+    streakMin: live ? Math.round((now.getTime() - Date.parse(day.presence!.streakStartAt)) / 60000) : 0,
   };
 }
 

package/src/types.ts

@@ -1,4 +1,4 @@
-export type EventKind = "prompt" | "report" | "output" | "interrupt" | "reject" | "question" | "plan_review" | "mode_change" | "activity";
+export type EventKind = "prompt" | "report" | "output" | "interrupt" | "reject" | "answer" | "question" | "plan_review" | "mode_change" | "activity";
 export type Event = { ts: number; sessionId: string; kind: EventKind; tokens?: number };
 export type Transcript = { path: string; text: string };
 export type Window = { to: string; days: number; now?: Date }; // to = "YYYY-MM-DD" local
@@ -14,4 +14,8 @@ export type HourBucket = Metrics & { hour: number; score: Score | null };
 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.
-export type Day = { date: string; peak: number | null; mean: number | null; activeMin: number; totals: Totals; buckets: HourBucket[]; asOf?: string };
+// `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 };