@drakulavich/zapara 0.3.1 → 0.5.0

package/src/render.ts

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

package/src/report.ts

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

package/src/scan.ts

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

package/src/score.ts

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

package/src/status.ts

@@ -1,10 +1,7 @@
+import { GAP_MS } from "./derive.ts";
 import type { Day, Level } from "./types.ts";
 
-// The status file's content, as data: today's load reduced to the nine values a
-// status line needs. Core, not shell — this file never reads the clock, the
-// environment or the file system, and never writes one; `now` arrives as an
-// argument and `src/statusfile.ts` does the writing. The field order below is
-// the file format (see the status-file design spec) and JSON.stringify keeps it.
+// The status file's nine values. The field order is the file format.
 export type Status = {
   schema: 1;
   asOf: string;
@@ -17,26 +14,26 @@ 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.
+// index and level are the day's `live` bucket, not the hour's: an hour's bucket
+// is nearly empty just after the hour turns. streakMin is measured against `now`,
+// not the bucket's: it must not reset on the hour or stop between two actions,
+// and it is over once the last action is more than GAP_MS behind `now`.
 export function statusOf(day: Day, now: Date): Status {
   const hour = now.getHours();
-  const bucket = day.buckets[hour];
+  const live = day.presence !== null && now.getTime() - Date.parse(day.presence.lastAt) <= GAP_MS;
   return {
     schema: 1,
     asOf: day.asOf ?? now.toISOString(),
     date: day.date,
     hour,
-    index: bucket?.score?.index ?? null,
-    level: bucket?.score?.level ?? null,
+    index: day.live?.score?.index ?? null,
+    level: day.live?.score?.level ?? null,
     peak: day.peak,
     activeMin: day.activeMin,
-    streakMin: bucket?.streakMin ?? 0,
+    streakMin: live ? Math.round((now.getTime() - Date.parse(day.presence!.streakStartAt)) / 60000) : 0,
   };
 }
 
-// One line of JSON, the fields in the order declared above, newline at the end.
 export function renderStatus(s: Status): string {
   return JSON.stringify(s) + "\n";
 }

package/src/statusfile.ts

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

package/src/types.ts

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