kankaku 0.1.0 → 0.4.5

package/src/adapters/pi-tracker.ts

@@ -1,22 +1,64 @@
+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, WorkRole } from "../domain/work-record.ts";
+import type { WorkRecord, WorkRecordCore, WorkRole } from "../domain/work-record.ts";
+import type { InflightStore } from "../ports/inflight-store.ts";
 import type { WorkLog } from "../ports/work-log.ts";
-import { formatReport, formatSessions, formatTasks, localDay, summarize } from "./report.ts";
+import { formatClients, formatReport, formatSessions, formatTasks, localDay, summarize, summarizeByClient } from "./report.ts";
 
 export interface PiTrackerDeps {
   tracker: WorkTracker;
   log: WorkLog;
+  /** Crash-recovery checkpoint store; see the "Crash recovery" README section. */
+  inflight: InflightStore;
   role: WorkRole;
   pid: number;
   parentPid: number;
   /** Status line refresh interval in ms. Defaults to 1000. */
   statusIntervalMs?: number;
+  /** Whether a pid is still alive. Defaults to signal-probing with `process.kill(pid, 0)`. */
+  isAlive?: (pid: number) => boolean;
+  /** 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;
+  /**
+   * Write an export file (name, content) under the kankaku dir and return
+   * its absolute path. Injected from `extension.ts` to keep this adapter
+   * free of filesystem code. `/kankaku export` notifies an error when this
+   * is not configured.
+   */
+  writeExportFile?: (name: string, content: string) => string;
 }
 
-const STATUS_KEY = "kankaku";
+/** 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 {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    // EPERM means the process exists but we lack permission to signal it — still alive.
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+// 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. */
@@ -25,11 +67,16 @@ export interface KankakuReportData {
   lines: string[];
 }
 
-function formatElapsed(ms: number): 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;
-  return `⏱ ${String(minutes).padStart(2, "0")}:${String(seconds).padStart(2, "0")}`;
+  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 {
@@ -54,36 +101,86 @@ function guarded<E>(fn: (event: E, ctx: ExtensionContext) => void): (event: E, c
  * records to a {@link WorkLog} and exposing the `/kankaku` report command.
  */
 export function createPiTracker(pi: ExtensionAPI, deps: PiTrackerDeps): void {
-  const { tracker, log, role, pid, parentPid } = deps;
+  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;
     }
-    if (ctx.hasUI) {
-      ctx.ui.setStatus(STATUS_KEY, 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();
-    ctx.ui.setStatus(STATUS_KEY, formatElapsed(0));
+    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));
+      ctx.ui.setStatus(STATUS_KEY, formatElapsed(Date.now() - runStartedAt, client));
     }, statusIntervalMs);
     statusTimer.unref?.();
   }
 
-  function buildRecord(core: NonNullable<ReturnType<WorkTracker["onSettled"]>>, ctx: ExtensionContext): WorkRecord {
+  /**
+   * 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;
+  }
+
+  function clientSources(project: string | undefined = deps.resolveProjectClient?.()): { session?: string; env?: string; project?: string } {
+    return {
+      session: sessionClient,
+      env: deps.envClient,
+      project,
+    };
+  }
+
+  function runClientSources(): ReturnType<typeof clientSources> {
+    if (!runProjectClient) {
+      runProjectClient = { value: deps.resolveProjectClient?.() };
+    }
+    return clientSources(runProjectClient.value);
+  }
+
+  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 sessionName = pi.getSessionName();
     return {
       ...core,
       role,
@@ -94,9 +191,23 @@ export function createPiTracker(pi: ExtensionAPI, deps: PiTrackerDeps): void {
       sessionFile: ctx.sessionManager.getSessionFile(),
       mode: ctx.mode,
       ...(model !== undefined ? { model } : {}),
+      ...(client !== undefined ? { client } : {}),
+      ...(sessionName !== undefined ? { sessionName } : {}),
     };
   }
 
+  /**
+   * Save an in-flight checkpoint of the run's current state, so a hard
+   * crash before the next one (or the final settle) still leaves a
+   * recoverable `interrupted` record. A no-op while idle.
+   */
+  function checkpoint(ctx: ExtensionContext): void {
+    const core = tracker.peek("interrupted");
+    if (core) {
+      inflight.save(buildRecord(core, ctx));
+    }
+  }
+
   pi.on(
     "before_agent_start",
     guarded((event, ctx) => {
@@ -114,9 +225,10 @@ export function createPiTracker(pi: ExtensionAPI, deps: PiTrackerDeps): void {
 
   pi.on(
     "turn_end",
-    guarded((event) => {
+    guarded((event, ctx) => {
       const message = event.message;
       const usage = message && "usage" in message ? message.usage : undefined;
+      const cost = usage && typeof usage.cost === "object" && usage.cost !== null ? usage.cost.total : undefined;
       tracker.onTurnEnd(
         usage
           ? {
@@ -124,10 +236,11 @@ export function createPiTracker(pi: ExtensionAPI, deps: PiTrackerDeps): void {
               output: usage.output,
               cacheRead: usage.cacheRead,
               cacheWrite: usage.cacheWrite,
-              cost: usage.cost.total,
+              cost,
             }
           : undefined,
       );
+      checkpoint(ctx);
     }),
   );
 
@@ -140,8 +253,9 @@ export function createPiTracker(pi: ExtensionAPI, deps: PiTrackerDeps): void {
 
   pi.on(
     "tool_execution_end",
-    guarded((event) => {
+    guarded((event, ctx) => {
       tracker.onToolEnd(event.toolCallId, event.result);
+      checkpoint(ctx);
     }),
   );
 
@@ -163,10 +277,17 @@ export function createPiTracker(pi: ExtensionAPI, deps: PiTrackerDeps): void {
     "agent_settled",
     guarded((_event, ctx) => {
       const core = tracker.onSettled();
-      if (core) {
-        log.append(buildRecord(core, ctx));
+      try {
+        if (core) {
+          log.append(buildRecord(core, ctx));
+        }
+      } finally {
+        // Always clean up, even when log.append above threw: an unpersisted
+        // checkpoint must not linger, and the status timer must not leak.
+        inflight.clear();
+        stopStatus(ctx);
+        runProjectClient = undefined;
       }
-      stopStatus(ctx);
     }),
   );
 
@@ -174,10 +295,31 @@ export function createPiTracker(pi: ExtensionAPI, deps: PiTrackerDeps): void {
     "session_shutdown",
     guarded((_event, ctx) => {
       const core = tracker.onShutdown();
-      if (core) {
-        log.append(buildRecord(core, ctx));
+      try {
+        if (core) {
+          log.append(buildRecord(core, ctx));
+        }
+      } finally {
+        inflight.clear();
+        stopStatus(ctx);
+        runProjectClient = undefined;
+      }
+    }),
+  );
+
+  pi.on(
+    "session_start",
+    guarded((_event, ctx) => {
+      sessionClient = restoreSessionClient(ctx);
+      showIdleStatus(ctx);
+
+      const recovered = inflight.recoverStale(isAlive);
+      for (const record of recovered) {
+        log.append(record);
+      }
+      if (recovered.length > 0 && ctx.hasUI) {
+        ctx.ui.notify(`kankaku: recovered ${recovered.length} interrupted record(s)`, "warning");
       }
-      stopStatus(ctx);
     }),
   );
 
@@ -199,17 +341,107 @@ export function createPiTracker(pi: ExtensionAPI, deps: PiTrackerDeps): void {
     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.",
+      "'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;

package/src/adapters/project-config.ts

@@ -0,0 +1,44 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { resolveKankakuDir } from "./kankaku-dir.ts";
+
+const CONFIG_FILE_NAME = "config.json";
+
+/**
+ * Read the project's default billing client from `<dir>/config.json`
+ * (`{ "client": "acme" }`), the lowest-precedence source in
+ * `domain/client-label.ts#resolveClient`. `dir` is the kankaku dir (same
+ * directory as the work log).
+ *
+ * Tolerates a missing file, malformed JSON, a non-object document, or a
+ * `client` field that is not a string — all return `undefined` rather than
+ * throwing, since this file is optional and hand-edited.
+ */
+export function readProjectClient(dir: string): string | undefined {
+  const filePath = join(dir, CONFIG_FILE_NAME);
+  if (!existsSync(filePath)) return undefined;
+
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(filePath, "utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
+    const client = (parsed as Record<string, unknown>)["client"];
+    return typeof client === "string" ? client : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Reads the project client from a kankaku dir resolved lazily against `fallbackCwd()` at call time. */
+export class LazyProjectClientSource {
+  private readonly dirOrRelative: string;
+  private readonly fallbackCwd: () => string;
+
+  constructor(dirOrRelative: string, fallbackCwd: () => string = () => process.cwd()) {
+    this.dirOrRelative = dirOrRelative;
+    this.fallbackCwd = fallbackCwd;
+  }
+
+  read(): string | undefined {
+    return readProjectClient(resolveKankakuDir(this.dirOrRelative, this.fallbackCwd()));
+  }
+}

package/src/adapters/report.ts

@@ -1,7 +1,11 @@
 import { buildTasks } from "../domain/task-view.ts";
 import type { SessionView, TaskView } from "../domain/task-view.ts";
+import { localDay } from "../domain/day.ts";
+import { finiteOrZero } from "../domain/work-record.ts";
 import type { WorkRecord, WorkRole } from "../domain/work-record.ts";
 
+export { localDay } from "../domain/day.ts";
+
 export interface RoleTotals {
   workMs: number;
   waitingMs: number;
@@ -9,6 +13,8 @@ export interface RoleTotals {
   count: number;
   /** Estimated cost in USD, as priced by pi's model table. */
   cost: number;
+  /** Per-tag total milliseconds summed across every record of this role. */
+  segments: Record<string, number>;
 }
 
 export interface TaskTotals {
@@ -17,6 +23,8 @@ export interface TaskTotals {
   workMs: number;
   /** Estimated cost in USD, orchestrator and subagents combined. */
   cost: number;
+  /** Per-tag total milliseconds summed across every task (orchestrator and subagents). */
+  segments: Record<string, number>;
 }
 
 export type Summary = Record<WorkRole, RoleTotals> & { tasks: TaskTotals };
@@ -30,17 +38,15 @@ export interface SummarizeOptions {
 
 const ROLES: WorkRole[] = ["orchestrator", "subagent"];
 
-/** Local (not UTC) calendar day of an ISO timestamp, as `YYYY-MM-DD`. */
-export function localDay(iso: string): string {
-  const date = new Date(iso);
-  const year = date.getFullYear();
-  const month = String(date.getMonth() + 1).padStart(2, "0");
-  const day = String(date.getDate()).padStart(2, "0");
-  return `${year}-${month}-${day}`;
+function emptyTotals(): RoleTotals {
+  return { workMs: 0, waitingMs: 0, wallMs: 0, count: 0, cost: 0, segments: {} };
 }
 
-function emptyTotals(): RoleTotals {
-  return { workMs: 0, waitingMs: 0, wallMs: 0, count: 0, cost: 0 };
+/** Add per-tag milliseconds from `segments` (missing on older records) into `into`. */
+function addSegments(into: Record<string, number>, segments: Record<string, number> | undefined): void {
+  for (const [tag, ms] of Object.entries(segments ?? {})) {
+    into[tag] = (into[tag] ?? 0) + ms;
+  }
 }
 
 /**
@@ -55,7 +61,7 @@ export function summarize(records: WorkRecord[], options: SummarizeOptions): Sum
   const summary: Summary = {
     orchestrator: emptyTotals(),
     subagent: emptyTotals(),
-    tasks: { count: 0, wallMs: 0, workMs: 0, cost: 0 },
+    tasks: { count: 0, wallMs: 0, workMs: 0, cost: 0, segments: {} },
   };
 
   for (const record of records) {
@@ -65,7 +71,8 @@ export function summarize(records: WorkRecord[], options: SummarizeOptions): Sum
     totals.waitingMs += record.waitingMs;
     totals.wallMs += record.wallMs;
     totals.count += 1;
-    totals.cost += record.usage.cost;
+    totals.cost += finiteOrZero(record.usage.cost);
+    addSegments(totals.segments, record.segments);
   }
 
   const tasks = buildTasks(records).filter((task) => targetDay === undefined || localDay(task.startedAt) === targetDay);
@@ -74,6 +81,7 @@ export function summarize(records: WorkRecord[], options: SummarizeOptions): Sum
     summary.tasks.wallMs += task.wallMs;
     summary.tasks.workMs += task.workMs;
     summary.tasks.cost += task.usage.cost;
+    addSegments(summary.tasks.segments, task.segments);
   }
 
   return summary;
@@ -98,6 +106,15 @@ function formatTime(iso: string): string {
   return `${hours}:${minutes}`;
 }
 
+/** Render non-zero segment tags as `tag Xm00s` pairs, sorted alphabetically, joined by `, `. Undefined when none are non-zero. */
+function formatSegmentTags(segments: Record<string, number>): string | undefined {
+  const tags = Object.keys(segments)
+    .filter((tag) => segments[tag]! > 0)
+    .sort();
+  if (tags.length === 0) return undefined;
+  return tags.map((tag) => `${tag} ${formatMinutes(segments[tag]!)}`).join(", ");
+}
+
 /** Render a short, human-readable summary for the `/kankaku` command. */
 export function formatReport(summary: Summary): string {
   const lines = ROLES.map((role) => {
@@ -107,27 +124,81 @@ export function formatReport(summary: Summary): string {
   lines.push(
     `tasks: ${summary.tasks.count}, wall ${formatMinutes(summary.tasks.wallMs)}, work ${formatMinutes(summary.tasks.workMs)}, ${formatCost(summary.tasks.cost)}`,
   );
+  const segmentTags = formatSegmentTags(summary.tasks.segments);
+  if (segmentTags !== undefined) {
+    lines.push(`segments: ${segmentTags}`);
+  }
   return lines.join(" | ");
 }
 
-/** Render one line per task: time, union-based wall/work, cost, subagent count, and a truncated prompt. */
+/** Render one line per task: time, client (when present), union-based wall/work, cost, non-zero segment tags, subagent count, and a truncated prompt. */
 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;
-      return `${formatTime(task.startedAt)}  wall ${formatMinutes(task.wallMs)}  work ${formatMinutes(task.workMs)}  ${formatCost(task.usage.cost)}  subagents ${task.subagents.length}  ${prompt}`;
+      const segmentTags = formatSegmentTags(task.segments);
+      const segmentPart = segmentTags !== undefined ? `  ${segmentTags}` : "";
+      const clientPart = task.client !== undefined ? `  client:${task.client}` : "";
+      return `${formatTime(task.startedAt)}${clientPart}  wall ${formatMinutes(task.wallMs)}  work ${formatMinutes(task.workMs)}  ${formatCost(task.usage.cost)}${segmentPart}  subagents ${task.subagents.length}  ${prompt}`;
     })
     .join("\n");
 }
 
-/** Render one line per session: truncated id, time range, union-based wall/work, cost, and task count. */
+export interface ClientTotals {
+  wallMs: number;
+  waitingMs: number;
+  workMs: number;
+  /** Estimated cost in USD, summed across this client's tasks. */
+  cost: number;
+  count: number;
+}
+
+/** Client name under which tasks without a resolved client are grouped. */
+const NO_CLIENT = "(none)";
+
+/**
+ * Aggregate tasks by billing client (see `domain/client-label.ts`), summing
+ * work/waiting/wall time, cost, and task count. Tasks without a `client`
+ * are grouped under `"(none)"`. Returned as a `Map` rather than a plain
+ * object so an attacker-controlled client name can never repoint a
+ * prototype property.
+ */
+export function summarizeByClient(tasks: TaskView[]): Map<string, ClientTotals> {
+  const totals = new Map<string, ClientTotals>();
+  for (const task of tasks) {
+    const key = task.client ?? NO_CLIENT;
+    const entry = totals.get(key) ?? { wallMs: 0, waitingMs: 0, workMs: 0, cost: 0, count: 0 };
+    entry.wallMs += task.wallMs;
+    entry.waitingMs += task.waitingMs;
+    entry.workMs += task.workMs;
+    entry.cost += finiteOrZero(task.usage.cost);
+    entry.count += 1;
+    totals.set(key, entry);
+  }
+  return totals;
+}
+
+/** Render one line per client, sorted alphabetically, with work/waiting/wall time, cost, and task count. */
+export function formatClients(totals: Map<string, ClientTotals>): string {
+  if (totals.size === 0) return "no clients";
+  return Array.from(totals.entries())
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(
+      ([client, t]) =>
+        `${client}  work ${formatMinutes(t.workMs)}  waiting ${formatMinutes(t.waitingMs)}  wall ${formatMinutes(t.wallMs)}  ${formatCost(t.cost)}  tasks ${t.count}`,
+    )
+    .join("\n");
+}
+
+/** Render one line per session: truncated id, time range, union-based wall/work, cost, non-zero segment tags, and task count. */
 export function formatSessions(sessions: SessionView[]): string {
   if (sessions.length === 0) return "no sessions";
   return sessions
-    .map(
-      (session) =>
-        `${session.sessionId.slice(0, 8)}  ${formatTime(session.startedAt)}–${formatTime(session.endedAt)}  wall ${formatMinutes(session.wallMs)}  work ${formatMinutes(session.workMs)}  ${formatCost(session.usage.cost)}  tasks ${session.tasks.length}`,
-    )
+    .map((session) => {
+      const segmentTags = formatSegmentTags(session.segments);
+      const segmentPart = segmentTags !== undefined ? `  ${segmentTags}` : "";
+      return `${session.sessionId.slice(0, 8)}  ${formatTime(session.startedAt)}–${formatTime(session.endedAt)}  wall ${formatMinutes(session.wallMs)}  work ${formatMinutes(session.workMs)}  ${formatCost(session.usage.cost)}${segmentPart}  tasks ${session.tasks.length}`;
+    })
     .join("\n");
 }