kankaku 0.4.5 → 0.4.6

package/README.md

@@ -201,9 +201,11 @@ it.
 
 ## Crash recovery
 
-While a run is open, each pi process periodically writes a checkpoint of
-its current record to `<KANKAKU_DIR>/inflight/<pid>.json` (after every
-`turn_end` and `tool_execution_end`), and removes it on a normal
+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
@@ -213,6 +215,13 @@ whose owning pid is no longer alive, appends each one to `worklog.jsonl` as
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kankaku",
-  "version": "0.4.5",
+  "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/file-inflight-store.ts

@@ -6,6 +6,9 @@ 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 {
@@ -15,6 +18,14 @@ function safeUnlink(filePath: string): void {
   }
 }
 
+/** 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
@@ -56,6 +67,11 @@ export class FileInflightStore implements InflightStore {
     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);
@@ -80,4 +96,20 @@ export class FileInflightStore implements InflightStore {
 
     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,4 +1,4 @@
-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";
@@ -27,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");

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/lazy-jsonl-work-log.ts

@@ -32,4 +32,8 @@ export class LazyJsonlWorkLog implements WorkLog {
   readAll(): WorkRecord[] {
     return this.resolveFor(this.fallbackCwd()).readAll();
   }
+
+  version(): string {
+    return this.resolveFor(this.fallbackCwd()).version();
+  }
 }

package/src/adapters/pi-tracker.ts

@@ -1,14 +1,13 @@
-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, resolveClient, resolveClientSource } from "../domain/client-label.ts";
-import { exportRows, toCsv, toJson } from "../domain/export.ts";
-import { WorkTracker } from "../domain/work-tracker.ts";
-import { buildSessions, buildTasks } from "../domain/task-view.ts";
 import type { WorkRecord, WorkRecordCore, WorkRole } from "../domain/work-record.ts";
+import type { WorkTracker } from "../domain/work-tracker.ts";
 import type { InflightStore } from "../ports/inflight-store.ts";
 import type { WorkLog } from "../ports/work-log.ts";
-import { formatClients, formatReport, formatSessions, formatTasks, localDay, summarize, summarizeByClient } from "./report.ts";
+import { createSessionClient } from "./session-client.ts";
+import { createStatusBar } from "./status-bar.ts";
+import { notifyError, registerKankakuCommand } from "./kankaku-command.ts";
+
+export type { KankakuReportData } from "./kankaku-command.ts";
 
 export interface PiTrackerDeps {
   tracker: WorkTracker;
@@ -39,13 +38,6 @@ export interface PiTrackerDeps {
   writeExportFile?: (name: string, content: string) => string;
 }
 
-/** Persisted as a `kankaku-client` custom session entry so the session-level client survives a reload. */
-interface KankakuClientEntryData {
-  client: string | undefined;
-}
-
-const CLIENT_ENTRY_TYPE = "kankaku-client";
-
 /** Default `isAlive`: probe with signal 0 — no signal is sent, only existence/permission is checked. */
 function defaultIsAlive(pid: number): boolean {
   try {
@@ -57,34 +49,6 @@ function defaultIsAlive(pid: number): boolean {
   }
 }
 
-// Footer statuses are sorted alphabetically by key; "zz-" keeps kankaku last.
-const STATUS_KEY = "zz-kankaku";
-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[];
-}
-
-// U+FE0F forces emoji presentation so terminals do not fall back to monochrome text glyphs.
-const CLOCK_EMOJI = "\u{1F552}\uFE0F";
-const CLIENT_EMOJI = "\u{1F4BC}\uFE0F";
-
-function formatElapsed(ms: number, client?: string): string {
-  const totalSeconds = Math.max(0, Math.round(ms / 1000));
-  const minutes = Math.floor(totalSeconds / 60);
-  const seconds = totalSeconds % 60;
-  const elapsed = `${CLOCK_EMOJI} ${String(minutes).padStart(2, "0")}:${String(seconds).padStart(2, "0")}`;
-  return client ? `${elapsed} · ${client}` : elapsed;
-}
-
-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");
-}
-
 /** Wraps a handler so it never throws out of the pi event loop. */
 function guarded<E>(fn: (event: E, ctx: ExtensionContext) => void): (event: E, ctx: ExtensionContext) => void {
   return (event, ctx) => {
@@ -102,84 +66,38 @@ function guarded<E>(fn: (event: E, ctx: ExtensionContext) => void): (event: E, c
  */
 export function createPiTracker(pi: ExtensionAPI, deps: PiTrackerDeps): void {
   const { tracker, log, inflight, role, pid, parentPid } = deps;
-  const statusIntervalMs = deps.statusIntervalMs ?? 1000;
   const isAlive = deps.isAlive ?? defaultIsAlive;
 
-  let runStartedAt: number | undefined;
-  let statusTimer: NodeJS.Timeout | undefined;
-  /** Session-level client override, set with `/kankaku client <name>` and restored on `session_start`. Highest precedence in `resolveClient`. */
-  let sessionClient: string | undefined;
-  /** Project client read once per run (first record build) so checkpoints do not hit the filesystem repeatedly. */
-  let runProjectClient: { value: string | undefined } | undefined;
-
-  function stopStatus(ctx: ExtensionContext): void {
-    if (statusTimer) {
-      clearInterval(statusTimer);
-      statusTimer = undefined;
-    }
-    runStartedAt = undefined;
-    showIdleStatus(ctx);
-  }
-
-  /** While idle, keep the billing client visible (`💼 <client>`), or clear the status when none resolves. */
-  function showIdleStatus(ctx: ExtensionContext): void {
-    if (!ctx.hasUI) return;
-    // Reuse the project client cached for the run when one is still held, so
-    // settling does not re-read config.json; otherwise resolve it fresh.
-    const sources = runProjectClient ? clientSources(runProjectClient.value) : clientSources();
-    const client = role === "orchestrator" ? resolveClient(sources) : undefined;
-    ctx.ui.setStatus(STATUS_KEY, client ? `${CLIENT_EMOJI} ${client}` : undefined);
-  }
-
-  function startStatus(ctx: ExtensionContext): void {
-    if (!ctx.hasUI) return;
-    runStartedAt = Date.now();
-    const client = role === "orchestrator" ? resolveClient(runClientSources()) : undefined;
-    ctx.ui.setStatus(STATUS_KEY, formatElapsed(0, client));
-    statusTimer = setInterval(() => {
-      if (runStartedAt === undefined) return;
-      ctx.ui.setStatus(STATUS_KEY, formatElapsed(Date.now() - runStartedAt, client));
-    }, statusIntervalMs);
-    statusTimer.unref?.();
-  }
+  const sessionClient = createSessionClient({
+    role,
+    envClient: deps.envClient,
+    resolveProjectClient: deps.resolveProjectClient,
+  });
 
-  /**
-   * Scan the session's entries for the last `kankaku-client` custom entry
-   * and return the client it recorded (`undefined` when that entry cleared
-   * the label, or when no such entry exists yet).
-   */
-  function restoreSessionClient(ctx: ExtensionContext): string | undefined {
-    const entries = ctx.sessionManager.getEntries();
-    for (let i = entries.length - 1; i >= 0; i--) {
-      const entry = entries[i] as { type: string; customType?: string; data?: unknown };
-      if (entry.type === "custom" && entry.customType === CLIENT_ENTRY_TYPE) {
-        const data = entry.data as KankakuClientEntryData | undefined;
-        return data?.client;
-      }
-    }
-    return undefined;
-  }
+  const statusBar = createStatusBar({
+    intervalMs: deps.statusIntervalMs,
+    resolveRunClient: () => sessionClient.runClient(),
+    resolveIdleClient: () => sessionClient.idleClient(),
+  });
 
-  function clientSources(project: string | undefined = deps.resolveProjectClient?.()): { session?: string; env?: string; project?: string } {
-    return {
-      session: sessionClient,
-      env: deps.envClient,
-      project,
-    };
-  }
+  const kankakuCommand = registerKankakuCommand(pi, {
+    log,
+    sessionClient,
+    refreshIdleStatus: (ctx) => statusBar.showIdle(ctx),
+    writeExportFile: deps.writeExportFile,
+  });
 
-  function runClientSources(): ReturnType<typeof clientSources> {
-    if (!runProjectClient) {
-      runProjectClient = { value: deps.resolveProjectClient?.() };
-    }
-    return clientSources(runProjectClient.value);
+  /** `log.append` plus cache invalidation, so every append this process makes keeps the completion cache correct. */
+  function appendRecord(record: WorkRecord): void {
+    log.append(record);
+    kankakuCommand.invalidateClientNames();
   }
 
   function buildRecord(core: WorkRecordCore, ctx: ExtensionContext): WorkRecord {
     const model = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined;
     // Subagent children never carry their own client: they inherit the
     // orchestrator's label at task level (see task-view.ts).
-    const client = role === "orchestrator" ? resolveClient(runClientSources()) : undefined;
+    const client = sessionClient.runClient();
     const sessionName = pi.getSessionName();
     return {
       ...core,
@@ -212,7 +130,11 @@ export function createPiTracker(pi: ExtensionAPI, deps: PiTrackerDeps): void {
     "before_agent_start",
     guarded((event, ctx) => {
       tracker.onRunStart(event.prompt);
-      if (runStartedAt === undefined) startStatus(ctx);
+      statusBar.start(ctx);
+      // Checkpoint right away so a crash on the very first turn (before any
+      // turn_end/tool_execution_end) still leaves a recoverable in-flight
+      // record; see the "Crash recovery" README section.
+      checkpoint(ctx);
     }),
   );
 
@@ -279,14 +201,14 @@ export function createPiTracker(pi: ExtensionAPI, deps: PiTrackerDeps): void {
       const core = tracker.onSettled();
       try {
         if (core) {
-          log.append(buildRecord(core, ctx));
+          appendRecord(buildRecord(core, ctx));
         }
       } finally {
-        // Always clean up, even when log.append above threw: an unpersisted
+        // Always clean up, even when appendRecord above threw: an unpersisted
         // checkpoint must not linger, and the status timer must not leak.
         inflight.clear();
-        stopStatus(ctx);
-        runProjectClient = undefined;
+        statusBar.stop(ctx);
+        sessionClient.endRun();
       }
     }),
   );
@@ -297,12 +219,12 @@ export function createPiTracker(pi: ExtensionAPI, deps: PiTrackerDeps): void {
       const core = tracker.onShutdown();
       try {
         if (core) {
-          log.append(buildRecord(core, ctx));
+          appendRecord(buildRecord(core, ctx));
         }
       } finally {
         inflight.clear();
-        stopStatus(ctx);
-        runProjectClient = undefined;
+        statusBar.stop(ctx);
+        sessionClient.endRun();
       }
     }),
   );
@@ -310,166 +232,16 @@ export function createPiTracker(pi: ExtensionAPI, deps: PiTrackerDeps): void {
   pi.on(
     "session_start",
     guarded((_event, ctx) => {
-      sessionClient = restoreSessionClient(ctx);
-      showIdleStatus(ctx);
+      sessionClient.restore(ctx);
+      statusBar.showIdle(ctx);
 
       const recovered = inflight.recoverStale(isAlive);
       for (const record of recovered) {
-        log.append(record);
+        appendRecord(record);
       }
       if (recovered.length > 0 && ctx.hasUI) {
         ctx.ui.notify(`kankaku: recovered ${recovered.length} interrupted record(s)`, "warning");
       }
     }),
   );
-
-  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 = undefined;
-      pi.appendEntry<KankakuClientEntryData>(CLIENT_ENTRY_TYPE, { client: undefined });
-      showIdleStatus(ctx);
-      showReport(ctx, { title: "client", lines: ["client label cleared for this session"] });
-      return;
-    }
-
-    if (rest.length === 0) {
-      const sources = clientSources();
-      const client = resolveClient(sources);
-      const source = resolveClientSource(sources);
-      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 = name;
-    pi.appendEntry<KankakuClientEntryData>(CLIENT_ENTRY_TYPE, { client: name });
-    showIdleStatus(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}`] });
-  }
-
-  const COMMAND_TOKENS = ["all", "tasks", "sessions", "client", "clients", "export"];
-
-  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] ?? "";
-        const names = Array.from(
-          new Set(
-            log
-              .readAll()
-              .map((record) => record.client)
-              .filter((client): client is string => typeof client === "string"),
-          ),
-        ).sort();
-        return names.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);
-      }
-    },
-  });
 }

package/src/adapters/report.ts

@@ -131,12 +131,20 @@ export function formatReport(summary: Summary): string {
   return lines.join(" | ");
 }
 
-/** Render one line per task: time, client (when present), union-based wall/work, cost, non-zero segment tags, subagent count, and a truncated prompt. */
+/** Maximum visible width of a task prompt before it is truncated with an ellipsis marker. */
+const PROMPT_DISPLAY_LIMIT = 60;
+
+/** Truncate `text` to `limit` visible characters, appending `…` (counted within the limit) when it was cut. */
+function truncateWithEllipsis(text: string, limit: number): string {
+  return text.length > limit ? `${text.slice(0, limit - 1)}…` : text;
+}
+
+/** Render one line per task: time, client (when present), union-based wall/work, cost, non-zero segment tags, subagent count, and a truncated prompt (`…` marks a cut). */
 export function formatTasks(tasks: TaskView[]): string {
   if (tasks.length === 0) return "no tasks";
   return tasks
     .map((task) => {
-      const prompt = task.prompt.length > 60 ? task.prompt.slice(0, 60) : task.prompt;
+      const prompt = truncateWithEllipsis(task.prompt, PROMPT_DISPLAY_LIMIT);
       const segmentTags = formatSegmentTags(task.segments);
       const segmentPart = segmentTags !== undefined ? `  ${segmentTags}` : "";
       const clientPart = task.client !== undefined ? `  client:${task.client}` : "";

package/src/adapters/session-client.ts

@@ -0,0 +1,116 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { resolveClient, resolveClientSource } from "../domain/client-label.ts";
+import type { ClientSourceName, ClientSources } from "../domain/client-label.ts";
+import type { WorkRole } from "../domain/work-record.ts";
+
+/** Persisted as a `kankaku-client` custom session entry so the session-level client survives a reload. */
+export interface KankakuClientEntryData {
+  client: string | undefined;
+}
+
+export const CLIENT_ENTRY_TYPE = "kankaku-client";
+
+export interface SessionClientDeps {
+  role: WorkRole;
+  /** Default billing client for this project, from `KANKAKU_CLIENT` (config.ts). See `domain/client-label.ts`. */
+  envClient?: string;
+  /**
+   * Lazily reads the project's default billing client from
+   * `<kankaku dir>/config.json`. Injected from `extension.ts` so this
+   * adapter stays free of filesystem code.
+   */
+  resolveProjectClient?: () => string | undefined;
+}
+
+export interface SessionClient {
+  /** Restore the session-level client from the last `kankaku-client` custom entry; call on `session_start`. */
+  restore(ctx: ExtensionContext): void;
+  /** Set (or clear with `undefined`) the session client and persist it as a durable session entry. */
+  set(pi: ExtensionAPI, client: string | undefined): void;
+  /** Current client sources (session > env > project), reading the project client fresh unless `project` is given. */
+  sources(project?: string | undefined): ClientSources;
+  /** The effective client from {@link sources}, regardless of role. */
+  effectiveClient(): string | undefined;
+  /** Which source produced {@link effectiveClient}. */
+  effectiveSource(): ClientSourceName | undefined;
+  /** Role-gated client for the in-progress run (`undefined` for a subagent); caches the project client for the run. */
+  runClient(): string | undefined;
+  /** Role-gated client to show while idle, reusing the run's cached project client when still held. */
+  idleClient(): string | undefined;
+  /** Drop the per-run cached project client; call when a run settles or the session shuts down. */
+  endRun(): void;
+}
+
+/**
+ * Owns the session-level billing client override (`/kankaku client <name>`),
+ * its restore/persist round-trip through session entries, and client-source
+ * resolution for both the in-progress run and the idle status line. See
+ * README "Billing labels" and `domain/client-label.ts#resolveClient`.
+ */
+export function createSessionClient(deps: SessionClientDeps): SessionClient {
+  /** Session-level client override, set with `/kankaku client <name>` and restored on `session_start`. Highest precedence. */
+  let sessionClient: string | undefined;
+  /** Project client read once per run (first record build) so checkpoints do not hit the filesystem repeatedly. */
+  let runProjectClient: { value: string | undefined } | undefined;
+
+  function sources(project: string | undefined = deps.resolveProjectClient?.()): ClientSources {
+    return {
+      session: sessionClient,
+      env: deps.envClient,
+      project,
+    };
+  }
+
+  function runSources(): ClientSources {
+    if (!runProjectClient) {
+      runProjectClient = { value: deps.resolveProjectClient?.() };
+    }
+    return sources(runProjectClient.value);
+  }
+
+  /**
+   * Scan the session's entries for the last `kankaku-client` custom entry
+   * and restore the client it recorded (`undefined` when that entry cleared
+   * the label, or when no such entry exists yet).
+   */
+  function restore(ctx: ExtensionContext): void {
+    const entries = ctx.sessionManager.getEntries();
+    for (let i = entries.length - 1; i >= 0; i--) {
+      const entry = entries[i] as { type: string; customType?: string; data?: unknown };
+      if (entry.type === "custom" && entry.customType === CLIENT_ENTRY_TYPE) {
+        const data = entry.data as KankakuClientEntryData | undefined;
+        sessionClient = data?.client;
+        return;
+      }
+    }
+    sessionClient = undefined;
+  }
+
+  function set(pi: ExtensionAPI, client: string | undefined): void {
+    sessionClient = client;
+    pi.appendEntry<KankakuClientEntryData>(CLIENT_ENTRY_TYPE, { client });
+  }
+
+  function effectiveClient(): string | undefined {
+    return resolveClient(sources());
+  }
+
+  function effectiveSource(): ClientSourceName | undefined {
+    return resolveClientSource(sources());
+  }
+
+  function runClient(): string | undefined {
+    return deps.role === "orchestrator" ? resolveClient(runSources()) : undefined;
+  }
+
+  function idleClient(): string | undefined {
+    const idleSources = runProjectClient ? sources(runProjectClient.value) : sources();
+    return deps.role === "orchestrator" ? resolveClient(idleSources) : undefined;
+  }
+
+  function endRun(): void {
+    runProjectClient = undefined;
+  }
+
+  return { restore, set, sources, effectiveClient, effectiveSource, runClient, idleClient, endRun };
+}

package/src/adapters/status-bar.ts

@@ -0,0 +1,86 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+// U+FE0F forces emoji presentation so terminals do not fall back to monochrome text glyphs.
+const CLOCK_EMOJI = "\u{1F552}️";
+const CLIENT_EMOJI = "\u{1F4BC}️";
+
+/** Footer status key; footer statuses are sorted alphabetically by key, "zz-" keeps kankaku last. */
+export const STATUS_KEY = "zz-kankaku";
+
+export function formatElapsed(ms: number, client?: string): string {
+  const totalSeconds = Math.max(0, Math.round(ms / 1000));
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  const elapsed = `${CLOCK_EMOJI} ${String(minutes).padStart(2, "0")}:${String(seconds).padStart(2, "0")}`;
+  return client ? `${elapsed} · ${client}` : elapsed;
+}
+
+export interface StatusBarDeps {
+  /** Status line refresh interval in ms while a run is active. Defaults to 1000. */
+  intervalMs?: number;
+  /** Resolve the client label to show for the run that is starting now. */
+  resolveRunClient: () => string | undefined;
+  /** Resolve the client label to show while idle. */
+  resolveIdleClient: () => string | undefined;
+  /** Injectable for tests; defaults to the global timer functions. */
+  setInterval?: (handler: () => void, ms: number) => NodeJS.Timeout;
+  clearInterval?: (timer: NodeJS.Timeout) => void;
+  /** Injectable clock for tests; defaults to `Date.now`. */
+  now?: () => number;
+}
+
+export interface StatusBar {
+  /** Start (or, if already running, leave untouched) the elapsed-time status; a no-op without a UI. */
+  start(ctx: ExtensionContext): void;
+  /** Stop the elapsed-time status and fall back to the idle status. */
+  stop(ctx: ExtensionContext): void;
+  /** While idle, keep the billing client visible (`💼 <client>`), or clear the status when none resolves. */
+  showIdle(ctx: ExtensionContext): void;
+}
+
+/**
+ * Owns the `/kankaku` footer status: the running elapsed-time clock (with
+ * its refresh timer) while a run is active, and the idle billing-client
+ * label otherwise.
+ */
+export function createStatusBar(deps: StatusBarDeps): StatusBar {
+  const intervalMs = deps.intervalMs ?? 1000;
+  const scheduleInterval = deps.setInterval ?? setInterval;
+  const cancelInterval = deps.clearInterval ?? clearInterval;
+  const now = deps.now ?? Date.now;
+
+  let runStartedAt: number | undefined;
+  let statusTimer: NodeJS.Timeout | undefined;
+
+  function showIdle(ctx: ExtensionContext): void {
+    if (!ctx.hasUI) return;
+    const client = deps.resolveIdleClient();
+    ctx.ui.setStatus(STATUS_KEY, client ? `${CLIENT_EMOJI} ${client}` : undefined);
+  }
+
+  function start(ctx: ExtensionContext): void {
+    // Retries within the same run fire before_agent_start again; only the
+    // first one starts the timer.
+    if (runStartedAt !== undefined) return;
+    if (!ctx.hasUI) return;
+    runStartedAt = now();
+    const client = deps.resolveRunClient();
+    ctx.ui.setStatus(STATUS_KEY, formatElapsed(0, client));
+    statusTimer = scheduleInterval(() => {
+      if (runStartedAt === undefined) return;
+      ctx.ui.setStatus(STATUS_KEY, formatElapsed(now() - runStartedAt, client));
+    }, intervalMs);
+    statusTimer.unref?.();
+  }
+
+  function stop(ctx: ExtensionContext): void {
+    if (statusTimer) {
+      cancelInterval(statusTimer);
+      statusTimer = undefined;
+    }
+    runStartedAt = undefined;
+    showIdle(ctx);
+  }
+
+  return { start, stop, showIdle };
+}

package/src/domain/work-record.ts

@@ -79,6 +79,11 @@ export function finiteOrZero(value: unknown): number {
 const ROLES = new Set<WorkRole>(["orchestrator", "subagent"]);
 const STATUSES = new Set<WorkStatus>(["completed", "aborted", "interrupted"]);
 
+/** A finite, non-negative number: durations such as `wallMs` can never be negative. */
+function isNonNegativeFinite(value: unknown): boolean {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+
 /**
  * Runtime guard for a {@link WorkRecord} read back from disk. `readAll`
  * skips lines that parse as JSON but fail this check, so a torn write or a
@@ -98,9 +103,9 @@ export function isWorkRecord(value: unknown): value is WorkRecord {
     typeof record["prompt"] === "string" &&
     typeof record["startedAt"] === "string" &&
     typeof record["settledAt"] === "string" &&
-    Number.isFinite(record["wallMs"]) &&
-    Number.isFinite(record["waitingMs"]) &&
-    Number.isFinite(record["workMs"]) &&
+    isNonNegativeFinite(record["wallMs"]) &&
+    isNonNegativeFinite(record["waitingMs"]) &&
+    isNonNegativeFinite(record["workMs"]) &&
     typeof record["runs"] === "number" &&
     typeof record["turns"] === "number" &&
     typeof record["tools"] === "object" &&

package/src/domain/work-tracker.ts

@@ -158,7 +158,9 @@ export class WorkTracker {
         agent: openSubagent.agent,
         mode: openSubagent.mode,
         ...(taskId !== undefined ? { taskId } : {}),
-        ms: this.clock.now() - openSubagent.start,
+        // Clamped to >= 0: a backward clock jump while the subagent was
+        // running must never produce a negative duration.
+        ms: Math.max(0, this.clock.now() - openSubagent.start),
       });
       return;
     }
@@ -228,16 +230,18 @@ export class WorkTracker {
     if (!state) {
       throw new Error("buildRecord called without an open run");
     }
-    const wallMs = settledAt - state.startedAt;
+    // Clamped to >= 0: a backward clock jump (system clock adjustment, NTP
+    // correction) must never produce a negative duration.
+    const wallMs = Math.max(0, settledAt - state.startedAt);
 
     const closedSpans = state.waitingSpans.map((span) => ({ start: span.start, end: span.end ?? settledAt }));
-    const waitingMs = unionMs(clampIntervals(closedSpans, state.startedAt, settledAt));
-    const workMs = wallMs - waitingMs;
+    const waitingMs = Math.max(0, unionMs(clampIntervals(closedSpans, state.startedAt, settledAt)));
+    const workMs = Math.max(0, wallMs - waitingMs);
 
     const segmentEntries: Array<[string, number]> = [];
     for (const [tag, spans] of state.segmentSpans) {
       const closedTagSpans = spans.map((span) => ({ start: span.start, end: span.end ?? settledAt }));
-      const tagMs = unionMs(clampIntervals(closedTagSpans, state.startedAt, settledAt));
+      const tagMs = Math.max(0, unionMs(clampIntervals(closedTagSpans, state.startedAt, settledAt)));
       if (tagMs > 0) {
         segmentEntries.push([tag, tagMs]);
       }

package/src/ports/work-log.ts

@@ -3,4 +3,13 @@ import type { WorkRecord } from "../domain/work-record.ts";
 export interface WorkLog {
   append(record: WorkRecord): void;
   readAll(): WorkRecord[];
+  /**
+   * Optional cheap change signal: a value that changes whenever `append()`
+   * would change what `readAll()` returns, computable without reading the
+   * whole log (e.g. from file stat metadata). Callers that cache a view
+   * derived from `readAll()` (see `pi-tracker.ts`'s client-name completion
+   * cache) may use this to invalidate cheaply; a `WorkLog` that omits it
+   * simply leaves such callers relying on their own explicit invalidation.
+   */
+  version?(): string | number;
 }