@drakulavich/zapara 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to this project are documented here. The format follows
 
 ## [Unreleased]
 
+## [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
+- A window that includes today says when the snapshot was taken: `asOf` on today's JSON entry and an `as of HH:MM, this hour is still running` line under the tables.
+- `zapara status` writes today's load to `~/.claude/zapara/status.json` for a status line to read; the file format and the reader's refresh contract are in the spec.
+
+### Fixed
+- A window or output flag given twice (`--days 3 --days 5`) is a usage error, `--days given twice`, instead of the last value winning silently.
+- A transcript whose modification time is older than the window is still read when the last timestamp in it falls inside the window; before, a restored or synced file was dropped in full without a word.
+
 ## [0.2.0] - 2026-09-18
 
 ### Changed

package/README.md

@@ -38,29 +38,29 @@ Both pictures below come from the synthetic fixture in `tests/fixtures/busy-week
 
 ```
             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    ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ░  ░  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·     14    1h55
+Fri 18/09    ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ▓  ·  ·  ·  ·  ·  ·  ·  ·     81    1h00
+Sat 19/09    ░  ░  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·     24    1h55
 Sun 20/09    ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·      -    0h00
 
   ░ calm   ▒ warming   ▓ heating   █ fried
-  13h00 active   346 prompts   0 reports   100 decisions   5 sessions at once
+  21h35 active   348 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
+09:00      9  Calm        1        6     0    0      0     0     0       0     50m      600    0   4.5     0   0.1   4.2     0
+10:00     14  Calm        1        6     0    0      0     0     0       0    110m      600    0   4.5     0   0.1   9.2     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      9  Calm        1        6     0    0      0     0     0       0     50m      600    0   4.5     0   0.1   4.2     0
+21:00     14  Calm        1        6     0    0      0     0     0       0    110m      600    0   4.5     0   0.1   9.2     0
+23:00     19  Calm        1        6     0    0      0     0     0       0     50m      600    0   4.5     0   0.1   4.2    10
   no reports today
 ```
 
@@ -113,6 +113,7 @@ This one comes from the same `busy-week` fixture as the pictures above. The pict
 | `zapara 2026-09-14 --explain` | One day, with the six weighted components behind each index. |
 | `zapara card` | The last 14 days as one shareable picture, `zapara-card.png` in the current directory. |
 | `zapara card --days 30 --out me.webp` | Any window from 1 to 90 days; `.png`, `.webp` or `.html` by extension. `--json` prints the card's data instead. |
+| `zapara status` | Writes today's load to `~/.claude/zapara/status.json` for a status line to read, and prints the same line. See [Status line](#status-line). |
 
 | Flag | What it does |
 |---|---|
@@ -127,26 +128,49 @@ 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.
+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.
 
-Exit codes are 0 on success, 1 when the projects directory is missing or cannot be read (two different messages, neither 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 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, 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.
+
+## 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.
+
+```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}
+```
+
+| 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. 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` | Minutes of your presence in the day so far: the 5-minute slots covered by your prompts and the gaps of at most 10 minutes between them; `0` on a day with no prompt. |
+| `streakMin` | Minutes of the unbroken presence streak as of the current hour: your prompts no more than 10 minutes apart, across sessions; `0` when the hour has none. |
+
+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.
 
 ## Privacy
 
-zapara reads `~/.claude/projects/**/*.jsonl`, taking only files modified inside the window and skipping subagent transcripts under `subagents/`. 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/`. 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.
 
-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 you ask for, and nothing is installed into Claude Code.
+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.
 
 ## 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. A very old session touched today is read in full, but only its in-window events count.
+- 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.
 - 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 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.
+- A window that includes today is a snapshot: today's entry in the JSON carries `asOf`, the tables end with `as of HH:MM`, and two runs minutes apart differ while Claude Code is still writing. Today's numbers cover everything up to `asOf` and nothing timestamped after it, even if it lands in the same run. `zapara status` writes that snapshot to a file for a status line.
 
 ## Under the hood
 
@@ -197,7 +221,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 since the current presence streak began: your prompts no more than 10 minutes apart, across sessions, which may reach back before the hour. Agent activity between two prompts 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.

package/package.json

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

package/src/derive.ts

@@ -30,12 +30,20 @@ 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 };
+type Acc = { m: Metrics; sessions: Set<string>; slots: Set<number>; lastPromptSession: string | null; lastPrompt: { 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.
+// 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
+// `prompt` events 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.
+//
+// Prompts 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 a prompt into the window still covers the window's first slots.
 function foldEvents(sorted: Event[], startMs: number): Map<string, Acc> {
   const acc = new Map<string, Acc>(); // key "date|hour"
   const key = (ts: number): string => {
@@ -44,29 +52,38 @@ 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, lastPrompt: null }; acc.set(k, a); }
     return a;
   };
 
-  let prevActivityTs: number | null = null;
-  let streakStart: number | null = null;
+  let prevPromptTs: number | null = null;
+  let streakStart = 0; // always set by the first prompt, which starts a streak
   for (const e of sorted) {
-    if (e.kind === "activity") {
-      streakStart = prevActivityTs === null || e.ts - prevActivityTs > GAP_MS ? e.ts : streakStart;
-      prevActivityTs = e.ts;
+    if (e.kind === "prompt") {
+      const slot = Math.floor(e.ts / SLOT_MS);
+      // A prompt covers its own slot. Inside a streak the human sat through the
+      // gap too, so the pair also covers every slot between them; a prompt that
+      // starts a streak covers nothing behind it.
+      let from = slot;
+      if (prevPromptTs !== null && e.ts - prevPromptTs <= GAP_MS) from = Math.floor(prevPromptTs / 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
+      }
+      prevPromptTs = e.ts;
     }
-    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));
     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++;
         if (a.lastPromptSession !== null && a.lastPromptSession !== e.sessionId) a.m.contextSwitches++;
         a.lastPromptSession = e.sessionId;
+        a.lastPrompt = { ts: e.ts, streakStart };
         break;
       case "report": a.m.reports++; break;
       case "output": a.m.outputTokens += e.tokens ?? 0; break;
@@ -90,7 +107,7 @@ function buildDay(date: string, acc: Map<string, Acc>): Day {
     if (a) {
       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 = a.lastPrompt ? Math.round((a.lastPrompt.ts - a.lastPrompt.streakStart) / 60000) : 0;
     }
     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,
@@ -121,9 +138,14 @@ export function derive(events: Event[], w: Window): Day[] {
   const { startMs, endMs, cutoffMs, dates } = windowBounds(w);
   const sorted = events
     .map((e, i) => ({ e, i }))
-    .filter(({ e }) => e.ts >= cutoffMs && e.ts < endMs)
+    .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);
-  return dates.map((date) => buildDay(date, acc));
+  const days = dates.map((date) => buildDay(date, acc));
+  if (w.now) {
+    const today = localDate(w.now);
+    for (const d of days) if (d.date === today) d.asOf = w.now.toISOString();
+  }
+  return days;
 }

package/src/index.ts

@@ -9,6 +9,8 @@ import { localDate } from "./derive.ts";
 import { loadAssets, renderCard } from "./image.ts";
 import { renderDay, renderJson, renderWeek } from "./render.ts";
 import { report } from "./report.ts";
+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
@@ -25,6 +27,7 @@ function version(): string {
 const USAGE = `usage: zapara [window]                 the last 7 days, one cell per hour
        zapara today|yesterday|<date>   one day, one row per active hour
        zapara card [window] [--out]    the last 14 days as one picture
+       zapara status                   write today's load for a status line
 
 window:
   --days <N>        the last N days, 1..90; with --to, N days ending there
@@ -42,8 +45,9 @@ 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.
-type Args = { command: "grid" | "day" | "card"; to: string; days: number; explain: boolean; json: boolean; out: string; projects: string; color: boolean };
+// 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
@@ -106,6 +110,9 @@ 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.
+  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.
@@ -117,9 +124,15 @@ function parseArgs(argv: string[], now: Date, env: NodeJS.ProcessEnv, isTTY: boo
     // 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.
     const value = (negativeNumberIsValue = false): string => {
-      if (inline !== null) return inline;
-      const v = argv[++i];
-      if (v === undefined || (v.startsWith("-") && !(negativeNumberIsValue && /^-\d/.test(v)))) throw new UsageError(`${arg} needs a value`);
+      let v: string;
+      if (inline !== null) v = inline;
+      else {
+        const next = argv[++i];
+        if (next === undefined || (next.startsWith("-") && !(negativeNumberIsValue && /^-\d/.test(next)))) throw new UsageError(`${arg} needs a value`);
+        v = next;
+      }
+      if (seen.has(arg)) throw new UsageError(`${arg} given twice`);
+      seen.add(arg);
       return v;
     };
     switch (arg) {
@@ -144,11 +157,13 @@ function parseArgs(argv: string[], now: Date, env: NodeJS.ProcessEnv, isTTY: boo
   const [word] = positional;
   if (word === undefined) a.command = "grid";
   else if (word === "card") a.command = "card";
+  else if (word === "status") { a.command = "status"; a.to = localDate(now); a.days = 1; }
   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 or card)`);
+  else throw new UsageError(`unknown command${named(word)} (try today, yesterday, a date, card or status)`);
 
-  if (a.command === "day") {
-    if (days !== null || from !== null || to !== null) throw new UsageError("--days, --from and --to do not apply to a named day");
+  // 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));
@@ -166,9 +181,11 @@ function parseArgs(argv: string[], now: Date, env: NodeJS.ProcessEnv, isTTY: boo
 
 async function main(): Promise<number> {
   const argv = process.argv.slice(2);
-  const a = parseArgs(argv, new Date(), process.env, process.stdout.isTTY === true);
+  const now = new Date();
+  const a = parseArgs(argv, now, process.env, process.stdout.isTTY === true);
   if (a.command === "card") return card(a);
-  const days: Day[] = await report({ projects: a.projects, to: a.to, days: a.days });
+  if (a.command === "status") return status(a, now);
+  const days: Day[] = await report({ projects: a.projects, to: a.to, days: a.days, now });
   const data = a.command === "day" ? days[0] : days;
   if (a.json) console.log(renderJson(data!));
   else if (a.command === "day") console.log(renderDay(days[0]!, { explain: a.explain, color: a.color }));
@@ -176,6 +193,17 @@ 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.
+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));
+  await writeStatus(line, process.env);
+  process.stdout.write(line);
+  return 0;
+}
+
 async function card(a: Args): Promise<number> {
   const days: Day[] = await report({ projects: a.projects, to: a.to, days: a.days });
   const data = cardData(days, { days: a.days });

package/src/render.ts

@@ -10,6 +10,12 @@ const WEEKDAY = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
 const paint = (s: string, level: Level, color: boolean) => (color ? `\x1b[${ANSI[level]}m${s}\x1b[0m` : s);
 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.
+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) => {
   const [y, m, d] = date.split("-").map(Number) as [number, number, number];
   return `${WEEKDAY[new Date(y, m - 1, d).getDay()]} ${String(d).padStart(2, "0")}/${String(m).padStart(2, "0")}`;
@@ -34,7 +40,7 @@ export function renderWeek(days: Day[], color: boolean): string {
   // 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.
   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].join("\n");
+  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.
@@ -83,8 +89,10 @@ 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: today's plain behavior, the full header and nothing else.
-  if (active.length === 0) return line(cols, cols.map(([name]) => name));
+  // 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.
+  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"));
   const leftOut = cols.filter((col) => EVENT_COLS.has(col[0]) && !visible.includes(col));
@@ -102,6 +110,7 @@ export function renderDay(day: Day, opts: { explain: boolean; color: boolean }):
     const note = `  no ${leftOut.map(([name]) => FULL_NAME[name]).join(", ")} today`;
     lines.push(dim(note, opts.color));
   }
+  lines.push(...snapshotLine(day, opts.color));
   return lines.join("\n");
 }
 

package/src/report.ts

@@ -4,11 +4,11 @@ import { windowBounds } from "./derive.ts";
 import { scan } from "./scan.ts";
 import type { Day, Transcript } from "./types.ts";
 
-export type ReportOptions = { projects: string; to: string; days: number };
+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 };
+  const window = { to: o.to, days: o.days, now: o.now };
   const paths = await scan(o.projects, windowBounds(window).cutoffMs);
   const transcripts: Transcript[] = [];
   for (const path of paths) {

package/src/scan.ts

@@ -1,10 +1,10 @@
 import type { Dirent } from "node:fs";
-import { readdir, stat } from "node:fs/promises";
+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; a file whose mtime
-// is before the cutoff cannot hold events the report needs.
+// 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.
 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.
@@ -35,8 +35,32 @@ async function collect(dir: string, entries: Dirent[], cutoffMs: number, out: st
       } catch {}
     } else if (entry.isFile() && entry.name.endsWith(".jsonl")) {
       try {
-        if ((await stat(full)).mtimeMs >= cutoffMs) out.push(full);
+        if ((await stat(full)).mtimeMs >= cutoffMs || (await lastTimestampMs(full)) >= cutoffMs) out.push(full);
       } catch {}
     }
   }
 }
+
+// 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;
+async function lastTimestampMs(path: string): Promise<number> {
+  const fh = await open(path, "r");
+  try {
+    const size = (await fh.stat()).size;
+    const start = Math.max(0, size - TAIL_BYTES);
+    const buf = Buffer.alloc(size - start);
+    await fh.read(buf, 0, buf.length, start);
+    const tail = buf.toString("utf8");
+    let last = -Infinity;
+    for (const m of tail.matchAll(/"timestamp":"([^"]{20,40})"/g)) {
+      const ms = Date.parse(m[1]!);
+      if (!Number.isNaN(ms)) last = ms;
+    }
+    return last;
+  } finally {
+    await fh.close();
+  }
+}

package/src/status.ts

@@ -0,0 +1,42 @@
+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.
+export type Status = {
+  schema: 1;
+  asOf: string;
+  date: string;
+  hour: number;
+  index: number | null;
+  level: Level | null;
+  peak: number | null;
+  activeMin: number;
+  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.
+export function statusOf(day: Day, now: Date): Status {
+  const hour = now.getHours();
+  const bucket = day.buckets[hour];
+  return {
+    schema: 1,
+    asOf: day.asOf ?? now.toISOString(),
+    date: day.date,
+    hour,
+    index: bucket?.score?.index ?? null,
+    level: bucket?.score?.level ?? null,
+    peak: day.peak,
+    activeMin: day.activeMin,
+    streakMin: bucket?.streakMin ?? 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

@@ -0,0 +1,51 @@
+// 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`.
+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.
+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.
+  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.
+  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.
+    await chmod(dir, 0o700);
+    const handle = await open(tmp, "wx", 0o600);
+    created = true;
+    try { await handle.writeFile(line); } finally { await handle.close(); }
+    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

@@ -1,7 +1,7 @@
 export type EventKind = "prompt" | "report" | "output" | "interrupt" | "reject" | "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 };            // to = "YYYY-MM-DD" local
+export type Window = { to: string; days: number; now?: Date }; // to = "YYYY-MM-DD" local
 export type Metrics = {
   sessions: number; prompts: number; reports: number; outputTokens: number; interrupts: number; rejects: number; questions: number;
   plans: number; modeSwitches: number; decisions: number; contextSwitches: number;
@@ -12,4 +12,6 @@ export type Parts = { parallel: number; pace: number; supervision: number; readi
 export type Score = { index: number; level: Level; parts: Parts };
 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 };
-export type Day = { date: string; peak: number | null; mean: number | null; activeMin: number; totals: Totals; buckets: HourBucket[] };
+// 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 };