kankaku 0.1.0 → 0.4.6

package/README.md

@@ -55,6 +55,8 @@ Each line in `worklog.jsonl` is one JSON object:
   "sessionFile": "…",
   "mode": "tui",
   "model": "anthropic/claude-opus",
+  "client": "acme",
+  "sessionName": "billing sprint",
   "prompt": "first 200 chars of the first prompt",
   "startedAt": "2026-09-10T16:00:00.000Z",
   "settledAt": "2026-09-10T16:04:10.000Z",
@@ -65,6 +67,7 @@ Each line in `worklog.jsonl` is one JSON object:
   "turns": 9,
   "tools": { "bash": 4, "read": 3, "subagent_run": 1, "ask_user_question": 1 },
   "subagents": [{ "toolCallId": "…", "agent": "sdd-explore", "mode": "task", "taskId": "t1", "ms": 90000 }],
+  "segments": { "review": 62000 },
   "usage": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0, "cost": 0 },
   "status": "completed"
 }
@@ -122,22 +125,145 @@ Arguments are whitespace-separated and order-insensitive:
   session are shown instead.
 - `/kankaku sessions` — one line per session (id, time range, union
   wall/work, cost, task count) for today. Add `all` for every day.
+- `/kankaku client <name>` — set the billing client for the current pi
+  session. `/kankaku client` alone shows the effective client and which
+  source it came from; `/kankaku client --clear` removes the session-level
+  override. See "Billing labels" below.
+- `/kankaku clients` — one line per client (work/waiting/wall time, cost,
+  task count) for today. Add `all` for every day. Tasks with no resolved
+  client are grouped under `(none)`.
 
 Cost figures are the sum of `usage.cost` as priced by pi's model table
 (per-million-token rates in `models.json`, adjustable with `modelOverrides`).
 For subscription-based providers this is an estimate at API list prices, not
 an invoice.
 
-While an agent is running, pi's status bar shows a `⏱ mm:ss` indicator with
+While an agent is running, pi's status bar shows a `🕒 mm:ss · <client>` indicator (the client part appears only when one resolves); while idle it shows `💼 <client>`, or nothing when no client resolves. The entry is keyed `zz-kankaku` so it sorts last among extension statuses. The running indicator carries
 the elapsed time for the current run.
 
+## Billing labels
+
+Every `WorkRecord` can carry a `client` — who the work is billed to — so
+reports and exports can be grouped by client. The effective client is
+resolved from three sources, in decreasing precedence:
+
+1. **Session** — set with `/kankaku client <name>` (see above), persisted as
+   a `kankaku-client` custom session entry and restored on session reload.
+2. **`KANKAKU_CLIENT`** — the environment variable, a per-process default.
+3. **Project** — `client` in `<KANKAKU_DIR>/config.json` (e.g.
+   `{"client": "acme"}`), the project's own default.
+
+A client name must match `/^[A-Za-z0-9._-]{1,64}$/`; anything else (empty,
+too long, containing spaces or other characters) is ignored and resolution
+falls through to the next source.
+
+A `subagent_run` child process does not resolve its own client — a
+subagent's own `WorkRecord` never carries `client`. Instead, the **task**
+view (see "Task and session views") exposes the client from its
+orchestrator record only, so `/kankaku tasks`, `/kankaku clients`, and the
+export all see subagent work grouped under the task's (i.e. the
+orchestrator's) client.
+
+`sessionName` is also attached to every record from `pi.getSessionName()`,
+so reports can show which named session produced a task.
+
+## Tagged segments
+
+While a run is open, kankaku can also time tool executions that match a
+configured rule and tag the resulting span with a name — for example,
+knowing how much of a task went to gentle-ai's review-with-receipts step,
+which runs as `gentle-ai review ...` commands through the `bash` tool inside
+the prompt's run.
+
+The default rule tags `review`: tool `bash` running a command matching
+`/\bgentle-ai review\b/`. Configure rules with `KANKAKU_SEGMENTS`, a
+`;`-separated list of `tag=tool:regex` entries, e.g.:
+
+```
+KANKAKU_SEGMENTS="review=bash:gentle-ai review;commit=bash:git commit"
+```
+
+Setting `KANKAKU_SEGMENTS` replaces the default rule entirely; malformed
+entries (missing tag, tool or regex, or an invalid regex) are skipped.
+When several rules could match the same tool call, only the first one
+applies. A `WorkRecord`'s `segments` field is the **union** of milliseconds
+per tag within that one record, so overlapping matching calls are not
+double-counted. `TaskView.segments` and `SessionView.segments` are instead
+the **sum** of `segments` across the orchestrator and its children (or
+across a session's tasks): segment spans are not persisted to
+`worklog.jsonl`, so once a record settles there is nothing left to union
+across records, only per-record totals to add up.
+
+Note that the reviewer's own token cost is not observable here: gentle-pi
+runs it with `--no-extensions`, so kankaku never sees the reviewer's own
+prompt/tool events, only the `bash` call the orchestrator makes to invoke
+it.
+
+## Crash recovery
+
+While a run is open, each pi process writes a checkpoint of its current
+record to `<KANKAKU_DIR>/inflight/<pid>.json` — first as soon as the run
+starts (`before_agent_start`), so even a crash on the very first turn still
+leaves a checkpoint, and then again after every `turn_end` and
+`tool_execution_end` — and removes it on a normal
+`agent_settled`/`session_shutdown`. If the process is killed outright
+(`kill -9`, power loss) before it can settle, the checkpoint file survives
+it. On the next pi start, `session_start` scans `inflight/` for checkpoints
+whose owning pid is no longer alive, appends each one to `worklog.jsonl` as
+`interrupted`, deletes the checkpoint file, and shows a
+`kankaku: recovered N interrupted record(s)` notice. `settledAt` on a
+recovered record is the time of its last checkpoint, not the actual crash
+time, so `wallMs`/`workMs` are a **lower bound** on the real duration.
+
+The same scan also sweeps `inflight/` for orphaned `.tmp` files: `save`
+writes to a temp file before renaming it into place, and a process killed
+between those two steps leaves the temp file behind. A stray `.tmp` file is
+deleted once its writer pid is no longer alive (or its name cannot be
+parsed); one still owned by a live writer — including this very process's
+own in-progress write — is left alone.
+
+## Export
+
+`/kankaku export [csv|json] [all]` writes one flat row per task (today's
+tasks by default, or every task with `all`) to
+`<KANKAKU_DIR>/export/tasks-<YYYY-MM-DD or all>.<csv|json>`, and confirms
+with the file's path and row count via the durable report card. Format
+defaults to `csv`; each subagent's own time is folded into its task's row
+rather than exported separately (see "Task and session views").
+
+Columns (in this order for CSV; the same fields for JSON):
+
+| Column | Meaning |
+| --- | --- |
+| `id` | Task id (the orchestrator record's `id`). |
+| `day` | Local calendar day (`YYYY-MM-DD`) the task started on. |
+| `startedAt` / `endedAt` | ISO timestamps of the task's span. |
+| `client` | Billing client, or empty when unresolved. |
+| `sessionName` | pi session display name, or empty. |
+| `sessionId` | pi session id, or empty. |
+| `project` | Project cwd. |
+| `status` | `completed`, `aborted`, or `interrupted`. |
+| `prompt` | First 200 chars of the prompt, newlines collapsed to spaces. |
+| `wallMs` / `waitingMs` / `workMs` | Union-based task timings (see "Task and session views"). |
+| `cost` | Estimated USD cost, orchestrator plus subagents. |
+| `tokensIn` / `tokensOut` / `cacheRead` | Token usage totals. |
+| `subagentCount` | Number of subagent records matched to the task. |
+| `segments` | JSON-encoded per-tag segment totals (see "Tagged segments"). |
+| `model` | The orchestrator record's model, or empty. |
+
 ## Environment variables
 
-- `KANKAKU_DIR`: directory for the work log, relative to the project cwd
-  unless given as an absolute path. Defaults to `.kankaku`.
+- `KANKAKU_DIR`: directory for the work log (`worklog.jsonl`) and the
+  crash-recovery checkpoints (`inflight/`, see above), relative to the
+  project cwd unless given as an absolute path. Defaults to `.kankaku`.
 - `KANKAKU_INTERACTIVE_TOOLS`: comma-separated list of tool names whose
   execution span counts as waiting time. Defaults to
   `ask_user_question,ask_user_choice`.
+- `KANKAKU_SEGMENTS`: `;`-separated `tag=tool:regex` rules for tagged
+  segments (see above). Defaults to the single `review` rule.
+- `KANKAKU_CLIENT`: default billing client for this project (see "Billing
+  labels" above). Lower precedence than the session-level
+  `/kankaku client` override, higher than `<KANKAKU_DIR>/config.json`.
 
 ## Limitations
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kankaku",
-  "version": "0.1.0",
+  "version": "0.4.6",
   "description": "pi extension that records agent work time per prompt, excluding waits for the user, with subagent linkage and task/session views",
   "license": "MIT",
   "author": "soyunninja",

package/src/adapters/export-writer.ts

@@ -0,0 +1,33 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { resolveKankakuDir } from "./kankaku-dir.ts";
+
+const EXPORT_SUBDIR = "export";
+
+/**
+ * Write `content` to `<dir>/export/<name>` (creating the `export`
+ * subdirectory as needed, overwriting any existing file with the same
+ * name) and return the absolute path it was written to.
+ */
+export function writeExport(dir: string, name: string, content: string): string {
+  const exportDir = join(dir, EXPORT_SUBDIR);
+  mkdirSync(exportDir, { recursive: true });
+  const filePath = resolve(join(exportDir, name));
+  writeFileSync(filePath, content);
+  return filePath;
+}
+
+/** Writes exports under a kankaku dir resolved lazily against `fallbackCwd()` at call time. */
+export class LazyExportWriter {
+  private readonly dirOrRelative: string;
+  private readonly fallbackCwd: () => string;
+
+  constructor(dirOrRelative: string, fallbackCwd: () => string = () => process.cwd()) {
+    this.dirOrRelative = dirOrRelative;
+    this.fallbackCwd = fallbackCwd;
+  }
+
+  write(name: string, content: string): string {
+    return writeExport(resolveKankakuDir(this.dirOrRelative, this.fallbackCwd()), name, content);
+  }
+}

package/src/adapters/file-inflight-store.ts

@@ -0,0 +1,115 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { isWorkRecord } from "../domain/work-record.ts";
+import type { WorkRecord } from "../domain/work-record.ts";
+import type { InflightStore } from "../ports/inflight-store.ts";
+
+const INFLIGHT_DIR_NAME = "inflight";
+const JSON_EXT = ".json";
+const TMP_EXT = ".tmp";
+/** Matches `save`'s tmp filename: `<ownerPid>.json.<writerPid>.<timestamp>.tmp`. */
+const TMP_NAME_PATTERN = /\.json\.(\d+)\.\d+\.tmp$/;
+
+function safeUnlink(filePath: string): void {
+  try {
+    unlinkSync(filePath);
+  } catch {
+    // Best effort: another process may have already removed it.
+  }
+}
+
+/** The writer pid embedded in a `save` tmp filename, or `undefined` when it cannot be parsed. */
+function parseTmpWriterPid(entry: string): number | undefined {
+  const match = TMP_NAME_PATTERN.exec(entry);
+  if (!match) return undefined;
+  const pid = Number(match[1]);
+  return Number.isFinite(pid) ? pid : undefined;
+}
+
+/**
+ * {@link InflightStore} backed by one checkpoint file per process,
+ * `<dir>/inflight/<pid>.json`. `save` writes to a temp file then renames
+ * it into place so a reader never observes a partially written checkpoint.
+ */
+export class FileInflightStore implements InflightStore {
+  private readonly dir: string;
+  private readonly pid: number;
+
+  constructor(dir: string, pid: number) {
+    this.dir = dir;
+    this.pid = pid;
+  }
+
+  private get inflightDir(): string {
+    return join(this.dir, INFLIGHT_DIR_NAME);
+  }
+
+  private filePathFor(pid: number): string {
+    return join(this.inflightDir, `${pid}${JSON_EXT}`);
+  }
+
+  save(record: WorkRecord): void {
+    mkdirSync(this.inflightDir, { recursive: true });
+    const target = this.filePathFor(this.pid);
+    const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(tmp, JSON.stringify(record));
+    renameSync(tmp, target);
+  }
+
+  clear(): void {
+    safeUnlink(this.filePathFor(this.pid));
+  }
+
+  recoverStale(isAlive: (pid: number) => boolean): WorkRecord[] {
+    if (!existsSync(this.inflightDir)) return [];
+
+    const recovered: WorkRecord[] = [];
+    const ownFileName = `${this.pid}${JSON_EXT}`;
+
+    for (const entry of readdirSync(this.inflightDir)) {
+      if (entry.endsWith(TMP_EXT)) {
+        this.sweepTmpEntry(entry, isAlive);
+        continue;
+      }
+
+      if (!entry.endsWith(JSON_EXT) || entry === ownFileName) continue;
+
+      const filePath = join(this.inflightDir, entry);
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(readFileSync(filePath, "utf8"));
+      } catch {
+        safeUnlink(filePath);
+        continue;
+      }
+
+      if (!isWorkRecord(parsed)) {
+        safeUnlink(filePath);
+        continue;
+      }
+
+      if (isAlive(parsed.pid)) continue;
+
+      recovered.push({ ...parsed, status: "interrupted" });
+      safeUnlink(filePath);
+    }
+
+    return recovered;
+  }
+
+  /**
+   * Delete a stray `save()` tmp file left behind by a writer that crashed
+   * between the write and the rename. Deleted when the writer pid is not
+   * alive, or when the filename cannot be parsed at all (nothing to check
+   * liveness against). A tmp file written by this very process is always
+   * left alone regardless of what `isAlive` reports, since a concurrent
+   * `save()` in this process may still be renaming it into place.
+   */
+  private sweepTmpEntry(entry: string, isAlive: (pid: number) => boolean): void {
+    const writerPid = parseTmpWriterPid(entry);
+    if (writerPid === process.pid) return;
+    if (writerPid === undefined || !isAlive(writerPid)) {
+      safeUnlink(join(this.inflightDir, entry));
+    }
+  }
+}

package/src/adapters/jsonl-work-log.ts

@@ -1,7 +1,8 @@
-import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import type { WorkLog } from "../ports/work-log.ts";
 import type { WorkRecord } from "../domain/work-record.ts";
+import { isWorkRecord } from "../domain/work-record.ts";
 
 const LOG_FILE_NAME = "worklog.jsonl";
 
@@ -26,6 +27,20 @@ export class JsonlWorkLog implements WorkLog {
     appendFileSync(this.filePath, `${JSON.stringify(record)}\n`);
   }
 
+  /**
+   * Cheap change signal: `mtimeMs:size` of the log file, computed with a
+   * single `statSync` rather than reading the file. `"0:0"` when the file
+   * does not exist yet (before the first `append`).
+   */
+  version(): string {
+    try {
+      const stats = statSync(this.filePath);
+      return `${stats.mtimeMs}:${stats.size}`;
+    } catch {
+      return "0:0";
+    }
+  }
+
   readAll(): WorkRecord[] {
     if (!existsSync(this.filePath)) return [];
     const content = readFileSync(this.filePath, "utf8");
@@ -34,7 +49,12 @@ export class JsonlWorkLog implements WorkLog {
       const trimmed = line.trim();
       if (!trimmed) continue;
       try {
-        records.push(JSON.parse(trimmed) as WorkRecord);
+        const parsed: unknown = JSON.parse(trimmed);
+        if (isWorkRecord(parsed)) {
+          records.push(parsed);
+        }
+        // Tolerate a structurally invalid record (e.g. an incompatible
+        // schema or a torn write that still parses as JSON); skip it.
       } catch {
         // Tolerate malformed lines (e.g. a torn write); skip them.
       }

package/src/adapters/kankaku-command.ts

@@ -0,0 +1,226 @@
+import type { AutocompleteItem } from "@earendil-works/pi-tui";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Box, Text } from "@earendil-works/pi-tui";
+import { isValidClient } from "../domain/client-label.ts";
+import { exportRows, toCsv, toJson } from "../domain/export.ts";
+import { buildSessions, buildTasks } from "../domain/task-view.ts";
+import type { WorkLog } from "../ports/work-log.ts";
+import { formatClients, formatReport, formatSessions, formatTasks, localDay, summarize, summarizeByClient } from "./report.ts";
+import type { SessionClient } from "./session-client.ts";
+
+const REPORT_ENTRY_TYPE = "kankaku-report";
+
+/** Durable report rendered inside the chat transcript; never sent to the LLM. */
+export interface KankakuReportData {
+  title: string;
+  lines: string[];
+}
+
+/** Notify the user of an error through the UI, when one is available. */
+export function notifyError(ctx: ExtensionContext, error: unknown): void {
+  if (!ctx.hasUI) return;
+  const message = error instanceof Error ? error.message : String(error);
+  ctx.ui.notify(`kankaku: ${message}`, "error");
+}
+
+const COMMAND_TOKENS = ["all", "tasks", "sessions", "client", "clients", "export"];
+
+export interface KankakuCommandDeps {
+  log: WorkLog;
+  sessionClient: SessionClient;
+  /** Refresh the idle status line, e.g. after `/kankaku client` changes the session client. */
+  refreshIdleStatus: (ctx: ExtensionContext) => void;
+  /**
+   * Write an export file (name, content) under the kankaku dir and return
+   * its absolute path. `/kankaku export` notifies an error when this is not
+   * configured.
+   */
+  writeExportFile?: (name: string, content: string) => string;
+}
+
+export interface KankakuCommand {
+  /** Drop the cached client-name list so the next completion re-reads the log. */
+  invalidateClientNames(): void;
+}
+
+/**
+ * Registers the `/kankaku` command (report/tasks/sessions/clients/export/
+ * client), its argument completions, and the durable report entry renderer.
+ */
+export function registerKankakuCommand(pi: ExtensionAPI, deps: KankakuCommandDeps): KankakuCommand {
+  const { log, sessionClient } = deps;
+
+  /**
+   * Cached, sorted, de-duplicated client names for `/kankaku client <prefix>`
+   * autocomplete, so pressing a key does not re-read the whole worklog.
+   * Invalidated whenever this process appends a record, and — when `log`
+   * exposes the optional `version()` signal — whenever that signal changes,
+   * so a change from another process is picked up too.
+   */
+  let clientNamesCache: string[] | undefined;
+  let clientNamesCacheVersion: string | number | undefined;
+
+  function invalidateClientNames(): void {
+    clientNamesCache = undefined;
+  }
+
+  function clientNames(): string[] {
+    const currentVersion = log.version?.();
+    const versionUnchanged = log.version === undefined || currentVersion === clientNamesCacheVersion;
+    if (clientNamesCache !== undefined && versionUnchanged) {
+      return clientNamesCache;
+    }
+    const names = Array.from(
+      new Set(
+        log
+          .readAll()
+          .map((record) => record.client)
+          .filter((client): client is string => typeof client === "string"),
+      ),
+    ).sort();
+    clientNamesCache = names;
+    clientNamesCacheVersion = currentVersion;
+    return names;
+  }
+
+  pi.registerEntryRenderer<KankakuReportData>(REPORT_ENTRY_TYPE, (entry, _options, theme) => {
+    const data = entry.data ?? { title: "kankaku", lines: [] };
+    const box = new Box(1, 0, (text) => theme.bg("customMessageBg", text));
+    box.addChild(new Text(`${theme.fg("accent", "kankaku")} ${data.title}`, 0, 0));
+    for (const line of data.lines) {
+      box.addChild(new Text(line, 0, 0));
+    }
+    return box;
+  });
+
+  function showReport(ctx: ExtensionContext, report: KankakuReportData): void {
+    if (ctx.hasUI) {
+      pi.appendEntry<KankakuReportData>(REPORT_ENTRY_TYPE, report);
+      return;
+    }
+    ctx.ui.notify(`${report.title}\n${report.lines.join("\n")}`);
+  }
+
+  /** Handle `/kankaku client [<name> | --clear]`; `rest` excludes the leading `client` token. */
+  function handleClientCommand(rest: string[], ctx: ExtensionContext): void {
+    if (rest.length === 1 && rest[0] === "--clear") {
+      sessionClient.set(pi, undefined);
+      deps.refreshIdleStatus(ctx);
+      showReport(ctx, { title: "client", lines: ["client label cleared for this session"] });
+      return;
+    }
+
+    if (rest.length === 0) {
+      const client = sessionClient.effectiveClient();
+      const source = sessionClient.effectiveSource();
+      const line = client !== undefined ? `client: ${client} (from ${source})` : "client: none";
+      showReport(ctx, { title: "client", lines: [line] });
+      return;
+    }
+
+    const name = rest.join(" ");
+    if (!isValidClient(name)) {
+      notifyError(ctx, new Error(`invalid client name: ${name}`));
+      return;
+    }
+    sessionClient.set(pi, name);
+    deps.refreshIdleStatus(ctx);
+    showReport(ctx, { title: "client", lines: [`client set to ${name}`] });
+  }
+
+  /** Handle `/kankaku export [csv|json] [all]`; `rest` excludes the leading `export` token. Default format is csv. */
+  function handleExportCommand(rest: string[], ctx: ExtensionContext): void {
+    if (!deps.writeExportFile) {
+      notifyError(ctx, new Error("export is not configured"));
+      return;
+    }
+
+    const all = rest.includes("all");
+    const format: "csv" | "json" = rest.includes("json") ? "json" : "csv";
+    const records = log.readAll();
+    const today = localDay(new Date().toISOString());
+    const tasks = buildTasks(records).filter((task) => all || localDay(task.startedAt) === today);
+    const rows = exportRows(tasks);
+    const content = format === "json" ? toJson(rows) : toCsv(rows);
+    const name = `tasks-${all ? "all" : today}.${format}`;
+    const path = deps.writeExportFile(name, content);
+    showReport(ctx, { title: "export", lines: [`wrote ${rows.length} row(s) to ${path}`] });
+  }
+
+  pi.registerCommand("kankaku", {
+    description:
+      "Show kankaku work-time totals for today. Args (any order): 'all' for every record, " +
+      "'tasks' for this session's tasks ('tasks all' for every session), 'sessions' for today's sessions, " +
+      "'client <name>' to set the session billing client, 'client' to show the effective one and its source, " +
+      "'client --clear' to clear it, 'clients' for per-client totals today ('clients all' for every day), " +
+      "'export [csv|json] [all]' to write today's (or every) task as a file.",
+    getArgumentCompletions: (argumentPrefix: string): AutocompleteItem[] => {
+      const clientMatch = /^client\s+(\S*)$/.exec(argumentPrefix);
+      if (clientMatch) {
+        const prefix = clientMatch[1] ?? "";
+        return clientNames()
+          .filter((name) => name.startsWith(prefix))
+          .map((name) => ({ value: name, label: name }));
+      }
+      return COMMAND_TOKENS.filter((value) => value.startsWith(argumentPrefix)).map((value) => ({ value, label: value }));
+    },
+    handler: async (args, ctx) => {
+      try {
+        const tokens = args.trim().split(/\s+/).filter(Boolean);
+
+        if (tokens[0] === "client") {
+          handleClientCommand(tokens.slice(1), ctx);
+          return;
+        }
+
+        if (tokens[0] === "export") {
+          handleExportCommand(tokens.slice(1), ctx);
+          return;
+        }
+
+        const all = tokens.includes("all");
+        const records = log.readAll();
+        const today = localDay(new Date().toISOString());
+
+        if (tokens.includes("clients")) {
+          const tasks = buildTasks(records).filter((task) => all || localDay(task.startedAt) === today);
+          showReport(ctx, {
+            title: all ? "clients (all days)" : "clients (today)",
+            lines: formatClients(summarizeByClient(tasks)).split("\n"),
+          });
+          return;
+        }
+
+        if (tokens.includes("tasks")) {
+          const sessionId = ctx.sessionManager.getSessionId();
+          const scoped = all || !sessionId;
+          const tasks = buildTasks(records).filter((task) => scoped || task.sessionId === sessionId);
+          showReport(ctx, {
+            title: scoped ? "tasks (every session)" : "tasks (this session)",
+            lines: formatTasks(tasks).split("\n"),
+          });
+          return;
+        }
+
+        if (tokens.includes("sessions")) {
+          const tasks = buildTasks(records).filter((task) => all || localDay(task.startedAt) === today);
+          showReport(ctx, {
+            title: all ? "sessions (all days)" : "sessions (today)",
+            lines: formatSessions(buildSessions(tasks)).split("\n"),
+          });
+          return;
+        }
+
+        const summary = summarize(records, { all });
+        showReport(ctx, {
+          title: all ? "summary (all days)" : "summary (today)",
+          lines: formatReport(summary).split(" | "),
+        });
+      } catch (error) {
+        notifyError(ctx, error);
+      }
+    },
+  });
+
+  return { invalidateClientNames };
+}

package/src/adapters/kankaku-dir.ts

@@ -0,0 +1,10 @@
+import { isAbsolute, join } from "node:path";
+
+/**
+ * Resolve the kankaku data directory: an absolute `dirOrRelative` is used
+ * as-is, a relative one is joined against `cwd`. Shared by every lazy
+ * adapter so the rule lives in exactly one place.
+ */
+export function resolveKankakuDir(dirOrRelative: string, cwd: string): string {
+  return isAbsolute(dirOrRelative) ? dirOrRelative : join(cwd, dirOrRelative);
+}

package/src/adapters/lazy-file-inflight-store.ts

@@ -0,0 +1,43 @@
+import type { WorkRecord } from "../domain/work-record.ts";
+import type { InflightStore } from "../ports/inflight-store.ts";
+import { FileInflightStore } from "./file-inflight-store.ts";
+import { resolveKankakuDir } from "./kankaku-dir.ts";
+
+/**
+ * {@link InflightStore} that resolves a relative checkpoint directory
+ * lazily, mirroring {@link LazyJsonlWorkLog}: against the project of the
+ * first saved record, or against `fallbackCwd()` when `clear` or
+ * `recoverStale` happens before any record was saved in this process
+ * (e.g. `session_start`, which runs before `before_agent_start`).
+ */
+export class LazyFileInflightStore implements InflightStore {
+  private readonly dirOrRelative: string;
+  private readonly pid: number;
+  private readonly fallbackCwd: () => string;
+  private resolved: FileInflightStore | undefined;
+
+  constructor(dirOrRelative: string, pid: number, fallbackCwd: () => string = () => process.cwd()) {
+    this.dirOrRelative = dirOrRelative;
+    this.pid = pid;
+    this.fallbackCwd = fallbackCwd;
+  }
+
+  private resolveFor(cwd: string): FileInflightStore {
+    if (!this.resolved) {
+      this.resolved = new FileInflightStore(resolveKankakuDir(this.dirOrRelative, cwd), this.pid);
+    }
+    return this.resolved;
+  }
+
+  save(record: WorkRecord): void {
+    this.resolveFor(record.project).save(record);
+  }
+
+  clear(): void {
+    this.resolveFor(this.fallbackCwd()).clear();
+  }
+
+  recoverStale(isAlive: (pid: number) => boolean): WorkRecord[] {
+    return this.resolveFor(this.fallbackCwd()).recoverStale(isAlive);
+  }
+}

package/src/adapters/lazy-jsonl-work-log.ts

@@ -1,7 +1,7 @@
-import { isAbsolute, join } from "node:path";
 import type { WorkRecord } from "../domain/work-record.ts";
 import type { WorkLog } from "../ports/work-log.ts";
 import { JsonlWorkLog } from "./jsonl-work-log.ts";
+import { resolveKankakuDir } from "./kankaku-dir.ts";
 
 /**
  * {@link WorkLog} that resolves a relative log directory lazily: against the
@@ -20,8 +20,7 @@ export class LazyJsonlWorkLog implements WorkLog {
 
   private resolveFor(cwd: string): JsonlWorkLog {
     if (!this.resolved) {
-      const dir = isAbsolute(this.dirOrRelative) ? this.dirOrRelative : join(cwd, this.dirOrRelative);
-      this.resolved = new JsonlWorkLog(dir);
+      this.resolved = new JsonlWorkLog(resolveKankakuDir(this.dirOrRelative, cwd));
     }
     return this.resolved;
   }
@@ -33,4 +32,8 @@ export class LazyJsonlWorkLog implements WorkLog {
   readAll(): WorkRecord[] {
     return this.resolveFor(this.fallbackCwd()).readAll();
   }
+
+  version(): string {
+    return this.resolveFor(this.fallbackCwd()).version();
+  }
 }