@drakulavich/zapara 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -5,6 +5,27 @@ All notable changes to this project are documented here. The format follows
 
 ## [Unreleased]
 
+## [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
+- The command line is the window and the view, not names for windows: `zapara` is the grid of the last 7 days, `zapara --days 30`, `zapara --to 2026-09-14` or `zapara --from 2026-09-01 --to 2026-09-14` any window up to 90 days; `zapara today`, `zapara yesterday` or `zapara 2026-09-14` one day, hour by hour; `zapara card` the picture, with the same window flags. `week` and `day` are gone. A date is `YYYY-MM-DD`, `today` or `yesterday` everywhere; `--days=30` works beside `--days 30`; `-V` beside `--version`.
+- A usage error prints its line and `run 'zapara --help' for usage`, exit 2, instead of the whole usage screen; `--help` is one screen under 80 columns.
+
+### Fixed
+- `--days -1` is answered by the range message (`--days must be 1..90, got -1`) instead of `--days needs a value`: a negative number is a value, not a flag.
+- A projects directory that exists but cannot be read says so (`projects directory cannot be read (check its permissions)`, exit 1) instead of `not found`; the message still names no path.
+- The README's screencast and card show on npmjs.com: both images use absolute raw.githubusercontent.com URLs, and the demo files left Git LFS, whose objects the raw endpoint serves as pointer text.
+
 ## [0.1.0] - 2026-09-18
 
 ### Added

package/README.md

@@ -3,12 +3,13 @@
 <p align="center">
   <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
   <a href="https://bun.sh"><img src="https://img.shields.io/badge/runtime-Bun-f9f1e1?logo=bun" alt="Bun"></a>
+  <a href="https://www.npmjs.com/package/@drakulavich/zapara"><img src="https://img.shields.io/npm/v/@drakulavich/zapara?logo=npm&color=cb3837" alt="npm"></a>
 </p>
 
 <p align="center"><b>How hard was today?</b> zapara reads the transcripts Claude Code already writes on your machine and scores every hour 0–100 from parallel sessions, prompt pace, agent supervision, model output, streak length and late-night work. Nothing leaves the machine, no message text is kept.</p>
 
 <p align="center">
-  <img src="assets/demo.webp" alt="zapara demo: week heatmap, day table, JSON" width="800">
+  <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.
@@ -19,11 +20,11 @@ Claude Code writes a JSONL transcript for every session under `~/.claude/project
 # Install Bun if you do not have it (zapara needs 1.4 or newer)
 curl -fsSL https://bun.sh/install | bash
 
-# Your week, straight from the registry
+# The last 7 days, straight from the registry
 bunx @drakulavich/zapara@latest
 
-# A day, with the components behind each index
-bunx @drakulavich/zapara@latest day --explain
+# Yesterday, hour by hour, with the components behind each index
+bunx @drakulavich/zapara@latest yesterday --explain
 
 # The card
 bunx @drakulavich/zapara@latest card
@@ -69,8 +70,8 @@ hour   index  level    sess  prompts  intr  rej  quest  plan  mode  ctx-sw  stre
 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:
 
 ```bash
-TZ=UTC bun src/index.ts week --projects tests/fixtures/busy-week --to 2026-09-20 --no-color
-TZ=UTC bun src/index.ts day 2026-09-14 --projects tests/fixtures/busy-week --explain --no-color
+TZ=UTC bun src/index.ts --projects tests/fixtures/busy-week --to 2026-09-20 --no-color
+TZ=UTC bun src/index.ts 2026-09-14 --projects tests/fixtures/busy-week --explain --no-color
 ```
 
 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.
@@ -86,12 +87,18 @@ zapara card                    # writes zapara-card.png in the current directory
 zapara card --out card.webp    # WebP instead; --out card.html writes the page itself
 ```
 
+On macOS, one more command puts the picture on the clipboard, ready to paste into a chat:
+
+```bash
+zapara card && osascript -e 'set the clipboard to (read (POSIX file "zapara-card.png") as «class PNGf»)'
+```
+
 ```
 The Marathoner: Longest streak 7h53m without a break, 68% of your hours calm.
 wrote zapara-card.png
 ```
 
-<p align="center"><img src="assets/card.webp" alt="zapara card: The Marathoner, longest streak 7h53m, 68% of hours calm" width="800"></p>
+<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.
 
@@ -99,45 +106,71 @@ This one comes from the same `busy-week` fixture as the pictures above. The pict
 
 | Command | What it does |
 |---|---|
-| `zapara` | Same as `zapara week`. |
-| `zapara week` | The last 7 days ending today, in local time. |
-| `zapara week --days 14 --to 2026-09-17` | Any window. `--days` takes an integer from 1 to 90. |
-| `zapara day` | Today, one row per hour that had activity. |
-| `zapara day 2026-09-14 --explain` | One day, with the six weighted components behind each index. |
+| `zapara` | The last 7 days ending today, one cell per hour, in local time. |
+| `zapara --days 30` | The last 30 days. `--days` takes an integer from 1 to 90. |
+| `zapara --from 2026-09-01 --to 2026-09-14` | Any window, both days inclusive, at most 90 days. `--to` alone is 7 days ending there, `--days 30 --to 2026-09-14` is 30 days ending there. |
+| `zapara today` | Today, one row per hour that had activity. `yesterday` likewise. |
+| `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 |
 |---|---|
+| `--days <N>`, `--from <date>`, `--to <date>` | The window. A date is `YYYY-MM-DD`, `today` or `yesterday`. `--days=30` works as well as `--days 30`. |
+| `--explain` | With a day: the six weighted parts behind each index. |
 | `--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. |
-| `--help` | Usage, exit 0. |
-| `--version` | The version from `package.json`, exit 0. |
+| `-h`, `--help` | Usage, exit 0. |
+| `-V`, `--version` | The version from `package.json`, exit 0. |
 
 Levels: calm 0–29, warming 30–59, heating 60–84, fried 85–100.
 
-`week` and `day` print a text table when stdout is a terminal and JSON otherwise, so `zapara week | 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, 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 cannot be read, and 2 for a usage error such as a bad date or an unknown flag. 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. |
+| `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. |
+
+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 `week` and `day` a pipe always gets JSON, and there is no flag to ask for text instead.
+- 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
 

package/package.json

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

package/src/derive.ts

@@ -121,9 +121,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
@@ -22,13 +24,30 @@ function version(): string {
   throw new Error("package.json has no version");
 }
 
-const USAGE = `usage: zapara [week] [--days N] [--to YYYY-MM-DD]
-       zapara day [YYYY-MM-DD] [--explain]
-       zapara card [--days N] [--to YYYY-MM-DD] [--out PATH.png|.webp|.html]
-flags: --json  --projects <dir>  --no-color  --help  --version
+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
+  --from <date>     first day; --to <date> last day, default today
+                    a date is YYYY-MM-DD, today or yesterday
+
+options:
+  --explain         with a day: the six weighted parts behind each index
+  --out <path>      with card: .png, .webp or .html (default zapara-card.png)
+  --json            the same data as JSON; a pipe gets JSON without asking
+  --projects <dir>  read this directory instead of ~/.claude/projects
+  --no-color        no ANSI colors; NO_COLOR does the same
+  -h, --help  -V, --version
+
 levels: calm 0-29  warming 30-59  heating 60-84  fried 85-100`;
+const HINT = "run 'zapara --help' for usage";
 
-type Args = { command: "week" | "day" | "card"; to: string; days: number; date: string | null; 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
@@ -37,68 +56,136 @@ class UsageError extends Error {}
 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.
+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}` : "");
+
 function validDate(s: string): boolean {
-  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(s);
+  const m = DATE.exec(s);
   if (!m) return false;
   const [y, mo, d] = [Number(m[1]), Number(m[2]), Number(m[3])];
   const dt = new Date(y, mo - 1, d);
   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));
+  if (!validDate(s)) throw new UsageError(`${what} must be YYYY-MM-DD, today or yesterday${got(s)}`);
+  return s;
+}
+
+// Calendar days from one date to another, inclusive; 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.
+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)}`);
+  const last = to === null ? localDate(now) : resolveDate("--to", to, now);
+  if (from === null) return { to: last, days: days === null ? defaultDays : Number(days) };
+  const first = resolveDate("--from", from, now);
+  const span = spanDays(first, last);
+  if (span < 1) throw new UsageError(`--from ${first} is after --to ${last}`);
+  if (span > 90) throw new UsageError(`--from ${first} to ${last} is ${span} days; the most is 90`);
+  return { to: last, days: span };
+}
+
 function parseArgs(argv: string[], now: Date, env: NodeJS.ProcessEnv, isTTY: boolean): Args {
-  const a: Args = { command: "week", to: localDate(now), days: 7, date: null, explain: false, json: false, out: "zapara-card.png", projects: join(homedir(), ".claude", "projects"), color: isTTY && !env.NO_COLOR };
-  let days: number | null = null;
+  const a: Args = { command: "grid", to: localDate(now), days: 7, explain: false, json: false, out: "zapara-card.png", projects: join(homedir(), ".claude", "projects"), color: isTTY && !env.NO_COLOR };
+  let days: string | null = null;
+  let from: string | null = null;
+  let to: string | null = null;
   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++) {
-    const arg = argv[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`).
-    const value = (): string => { const v = argv[++i]; if (v === undefined || v.startsWith("-")) throw new UsageError(`${arg} needs a value`); return v; };
+    // 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 => {
+      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) {
       case "--help":
-      case "-h": throw new HelpRequested();
-      case "--version": throw new VersionRequested();
-      case "--json": jsonFlag = true; break;
-      case "--explain": a.explain = true; break;
-      case "--no-color": a.color = false; break;
+      case "-h": bare(); throw new HelpRequested();
+      case "--version":
+      case "-V": bare(); throw new VersionRequested();
+      case "--json": bare(); jsonFlag = true; break;
+      case "--explain": bare(); a.explain = true; break;
+      case "--no-color": bare(); a.color = false; break;
       case "--projects": a.projects = value(); break;
-      case "--to": a.to = value(); break;
-      case "--days": { const v = value(); if (!/^\d+$/.test(v) || Number(v) < 1 || Number(v) > 90) throw new UsageError(`--days must be 1..90, got ${v}`); days = Number(v); break; }
+      case "--from": from = value(); break;
+      case "--to": to = value(); break;
+      case "--days": days = value(true); break;
       case "--out": a.out = value(); outGiven = true; break;
       default:
-        if (arg.startsWith("-")) throw new UsageError(`unknown flag ${arg}`);
+        if (arg.startsWith("-")) throw new UsageError(`unknown flag${named(arg)}`);
         positional.push(arg);
     }
   }
-  const [cmd, ...rest] = positional;
-  if (cmd === undefined || cmd === "week") { if (rest.length) throw new UsageError(`unexpected argument ${rest[0]}`); a.command = "week"; }
-  else if (cmd === "day") { a.command = "day"; a.date = rest[0] ?? a.to; if (rest.length > 1) throw new UsageError(`unexpected argument ${rest[1]}`); }
-  else if (cmd === "card") { a.command = "card"; if (rest.length) throw new UsageError(`unexpected argument ${rest[0]}`); }
-  else throw new UsageError(`unknown command ${cmd}`);
-  // Two weeks make a pattern; a week makes a picture of one week.
-  a.days = days ?? (a.command === "card" ? 14 : 7);
+  if (positional.length > 1) throw new UsageError(`unexpected argument${named(positional[1]!)}`);
+  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, 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.
   a.json = a.command === "card" ? jsonFlag : jsonFlag || !isTTY;
-  if (a.command !== "day" && a.explain) throw new UsageError("--explain applies to day only");
+  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 …`, so it must be one plain line:
+  // 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.
   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");
-  if (!validDate(a.to)) throw new UsageError(`--to must be YYYY-MM-DD, got ${a.to}`);
-  if (a.date !== null && !validDate(a.date)) throw new UsageError(`date must be YYYY-MM-DD, got ${a.date}`);
   return a;
 }
 
 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[] = a.command === "day"
-    ? await report({ projects: a.projects, to: a.date!, days: 1 })
-    : 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 }));
@@ -106,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 });
@@ -134,7 +232,7 @@ if (import.meta.main) {
       catch (err) { console.error(`zapara: ${err instanceof Error ? err.message : String(err)}`); process.exit(1); }
     }
     const msg = e instanceof Error ? e.message : String(e);
-    if (e instanceof UsageError) { console.error(`zapara: ${msg}\n${USAGE}`); process.exit(2); }
+    if (e instanceof UsageError) { console.error(`zapara: ${msg}\n${HINT}`); process.exit(2); }
     console.error(`zapara: ${msg}`);
     process.exit(1);
   });

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,40 +1,66 @@
-import { readdir, stat } from "node:fs/promises";
+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; 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.
+  let root;
   try {
     if (!(await stat(projects)).isDirectory()) throw new Error("not a directory");
-  } catch {
-    // No path in the message: it may be a value the user typed, or the
-    // homedir-derived default, and the CLI must never print a filesystem path.
+    root = await readdir(projects, { withFileTypes: true });
+  } catch (err) {
+    const code = (err as { code?: string }).code;
+    if (code === "EACCES" || code === "EPERM") throw new Error("projects directory cannot be read (check its permissions)");
     throw new Error("projects directory not found (pass --projects <dir>)");
   }
   const out: string[] = [];
-  await walk(projects, cutoffMs, out);
+  await collect(projects, root, cutoffMs, out);
   return out.sort();
 }
 
-// One directory at a time, so one unreadable directory or a symlink loop 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.
-async function walk(dir: string, cutoffMs: number, out: string[]): Promise<void> {
-  let entries;
-  try {
-    entries = await readdir(dir, { withFileTypes: true });
-  } catch {
-    return;
-  }
+// 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.
+async function collect(dir: string, entries: Dirent[], cutoffMs: number, out: string[]): Promise<void> {
   for (const entry of entries) {
     const full = join(dir, entry.name);
     if (entry.isDirectory()) {
-      if (entry.name !== "subagents") await walk(full, cutoffMs, out);
+      if (entry.name === "subagents") continue;
+      try {
+        await collect(full, await readdir(full, { withFileTypes: true }), cutoffMs, out);
+      } 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 };