kankaku 0.1.0 → 0.4.5

package/src/config.ts

@@ -1,3 +1,5 @@
+import type { SegmentRule } from "./domain/segment-rule.ts";
+
 export interface KankakuConfig {
   /** Directory for the work log, relative to the project cwd unless absolute. */
   dir: string;
@@ -5,12 +7,68 @@ export interface KankakuConfig {
   interactiveTools: string[];
   /** Tool name used to run subagents. */
   subagentTool: string;
+  /** Rules that tag a tool execution's span under a named segment (e.g. `review`). */
+  segmentRules: SegmentRule[];
+  /** Default billing client for this project, from `KANKAKU_CLIENT`. See `domain/client-label.ts`. */
+  client?: string;
 }
 
 const DEFAULT_DIR = ".kankaku";
 const DEFAULT_INTERACTIVE_TOOLS = ["ask_user_question", "ask_user_choice"];
 const SUBAGENT_TOOL = "subagent_run";
 
+/**
+ * Default segment rule: with gentle-ai, the review-with-receipts step runs
+ * as `gentle-ai review ...` commands through the `bash` tool, so tag that
+ * span `review`.
+ */
+const DEFAULT_SEGMENT_RULES: SegmentRule[] = [{ tag: "review", tool: "bash", pattern: /\bgentle-ai review\b/ }];
+
+/** Tags allowed for a segment rule: letters, digits, `_` and `-`, 1-32 chars. */
+const SAFE_TAG = /^[A-Za-z0-9_-]{1,32}$/;
+/** Property names that behave specially on a plain object; never usable as a tag. */
+const RESERVED_TAGS = new Set(["__proto__", "constructor", "prototype"]);
+
+function isSafeTag(tag: string): boolean {
+  return SAFE_TAG.test(tag) && !RESERVED_TAGS.has(tag);
+}
+
+/**
+ * Parse `KANKAKU_SEGMENTS`, a `;`-separated list of `tag=tool:regex`
+ * entries (example: `review=bash:gentle-ai review;commit=bash:git commit`).
+ * Malformed entries (missing tag, tool or regex, an invalid regex source,
+ * or a tag that is not a safe identifier such as `__proto__`) are skipped
+ * rather than failing the whole variable.
+ */
+function parseSegmentRules(raw: string): SegmentRule[] {
+  const rules: SegmentRule[] = [];
+
+  for (const entry of raw.split(";")) {
+    const trimmed = entry.trim();
+    if (!trimmed) continue;
+
+    const eqIndex = trimmed.indexOf("=");
+    if (eqIndex <= 0) continue;
+
+    const tag = trimmed.slice(0, eqIndex).trim();
+    const rest = trimmed.slice(eqIndex + 1);
+    const colonIndex = rest.indexOf(":");
+    if (colonIndex <= 0) continue;
+
+    const tool = rest.slice(0, colonIndex).trim();
+    const regexSource = rest.slice(colonIndex + 1).trim();
+    if (!tag || !tool || !regexSource || !isSafeTag(tag)) continue;
+
+    try {
+      rules.push({ tag, tool, pattern: new RegExp(regexSource) });
+    } catch {
+      continue;
+    }
+  }
+
+  return rules;
+}
+
 export function loadConfig(env: NodeJS.ProcessEnv = process.env): KankakuConfig {
   const dir = env["KANKAKU_DIR"]?.trim() || DEFAULT_DIR;
   const interactiveToolsRaw = env["KANKAKU_INTERACTIVE_TOOLS"]?.trim();
@@ -21,10 +79,17 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): KankakuConfig
         .filter((tool) => tool.length > 0)
     : DEFAULT_INTERACTIVE_TOOLS;
 
+  const segmentsRaw = env["KANKAKU_SEGMENTS"]?.trim();
+  const segmentRules = segmentsRaw ? parseSegmentRules(segmentsRaw) : DEFAULT_SEGMENT_RULES;
+
+  const client = env["KANKAKU_CLIENT"]?.trim() || undefined;
+
   return {
     dir,
     interactiveTools,
     subagentTool: SUBAGENT_TOOL,
+    segmentRules,
+    ...(client !== undefined ? { client } : {}),
   };
 }
 

package/src/domain/client-label.ts

@@ -0,0 +1,56 @@
+/**
+ * Client (billing target) label resolution: pure, no I/O.
+ *
+ * A client name identifies who a piece of work is billed to. It can come
+ * from three sources, in decreasing precedence: the pi session (set with
+ * `/kankaku client <name>`), the `KANKAKU_CLIENT` environment variable, or
+ * the project's `.kankaku/config.json`.
+ */
+
+/** Safe client name: letters, digits, `.`, `_`, `-`, 1-64 chars. */
+const CLIENT_PATTERN = /^[A-Za-z0-9._-]{1,64}$/;
+
+/** Property names that behave specially on a plain object; never usable as a client name. */
+const RESERVED_NAMES = new Set(["__proto__", "constructor", "prototype"]);
+
+export interface ClientSources {
+  /** Set for the current pi session via `/kankaku client <name>`. Highest precedence. */
+  session?: string;
+  /** From the `KANKAKU_CLIENT` environment variable. */
+  env?: string;
+  /** From the project's `.kankaku/config.json`. Lowest precedence. */
+  project?: string;
+}
+
+export type ClientSourceName = "session" | "env" | "project";
+
+/** `true` when `value` is a non-empty, safe client name. */
+export function isValidClient(value: string): boolean {
+  return CLIENT_PATTERN.test(value) && !RESERVED_NAMES.has(value);
+}
+
+/** Trim and validate a candidate client name; `undefined` when absent or invalid. */
+function normalize(value: string | undefined): string | undefined {
+  if (value === undefined) return undefined;
+  const trimmed = value.trim();
+  if (trimmed.length === 0) return undefined;
+  return isValidClient(trimmed) ? trimmed : undefined;
+}
+
+/**
+ * Resolve the effective client name from `session`, `env` and `project`
+ * sources, in that precedence order. Each candidate is trimmed; an empty
+ * string or a value that does not match the safe client-name pattern is
+ * treated as absent and resolution falls through to the next source.
+ */
+export function resolveClient(sources: ClientSources): string | undefined {
+  return normalize(sources.session) ?? normalize(sources.env) ?? normalize(sources.project);
+}
+
+/** Which source produced {@link resolveClient}'s result, or `undefined` when none applies. */
+export function resolveClientSource(sources: ClientSources): ClientSourceName | undefined {
+  if (normalize(sources.session) !== undefined) return "session";
+  if (normalize(sources.env) !== undefined) return "env";
+  if (normalize(sources.project) !== undefined) return "project";
+  return undefined;
+}

package/src/domain/day.ts

@@ -0,0 +1,8 @@
+/** 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}`;
+}

package/src/domain/export.ts

@@ -0,0 +1,107 @@
+import { localDay } from "./day.ts";
+import { finiteOrZero } from "./work-record.ts";
+import type { WorkStatus } from "./work-record.ts";
+import type { TaskView } from "./task-view.ts";
+
+/** One flat, spreadsheet-friendly row per {@link TaskView}. */
+export interface ExportRow {
+  id: string;
+  /** Local calendar day (`YYYY-MM-DD`) the task started on. */
+  day: string;
+  startedAt: string;
+  endedAt: string;
+  /** Empty string when the task has no resolved client. */
+  client: string;
+  /** Empty string when the orchestrator record has no session name. */
+  sessionName: string;
+  /** Empty string when the orchestrator record has no session id. */
+  sessionId: string;
+  project: string;
+  status: WorkStatus;
+  /** First 200 chars of the task's prompt, with newlines collapsed to spaces. */
+  prompt: string;
+  wallMs: number;
+  waitingMs: number;
+  workMs: number;
+  cost: number;
+  tokensIn: number;
+  tokensOut: number;
+  cacheRead: number;
+  subagentCount: number;
+  /** JSON-encoded `TaskView.segments` map. */
+  segments: string;
+  /** Empty string when the orchestrator record has no model. */
+  model: string;
+}
+
+/** First 200 chars of `prompt`, with `\n`/`\r` collapsed to a single space. */
+function truncatePrompt(prompt: string): string {
+  return prompt.slice(0, 200).replace(/\r\n|\r|\n/g, " ");
+}
+
+/** Build one flat {@link ExportRow} per task, in the same order as `tasks`. */
+export function exportRows(tasks: TaskView[]): ExportRow[] {
+  return tasks.map((task) => ({
+    id: task.id,
+    day: localDay(task.startedAt),
+    startedAt: task.startedAt,
+    endedAt: task.endedAt,
+    client: task.client ?? "",
+    sessionName: task.sessionName ?? "",
+    sessionId: task.sessionId ?? "",
+    project: task.project,
+    status: task.status,
+    prompt: truncatePrompt(task.prompt),
+    wallMs: task.wallMs,
+    waitingMs: task.waitingMs,
+    workMs: task.workMs,
+    cost: finiteOrZero(task.usage.cost),
+    tokensIn: finiteOrZero(task.usage.input),
+    tokensOut: finiteOrZero(task.usage.output),
+    cacheRead: finiteOrZero(task.usage.cacheRead),
+    subagentCount: task.subagents.length,
+    segments: JSON.stringify(task.segments),
+    model: task.orchestrator.model ?? "",
+  }));
+}
+
+/** Column order for {@link toCsv}'s header row, matching {@link ExportRow}'s field order. */
+const COLUMNS: Array<keyof ExportRow> = [
+  "id",
+  "day",
+  "startedAt",
+  "endedAt",
+  "client",
+  "sessionName",
+  "sessionId",
+  "project",
+  "status",
+  "prompt",
+  "wallMs",
+  "waitingMs",
+  "workMs",
+  "cost",
+  "tokensIn",
+  "tokensOut",
+  "cacheRead",
+  "subagentCount",
+  "segments",
+  "model",
+];
+
+/** RFC 4180 field quoting: quote a field containing `,`, `"`, or a newline; double any embedded quote. */
+function csvField(value: string | number): string {
+  const text = String(value);
+  return /[",\r\n]/.test(text) ? `"${text.replace(/"/g, '""')}"` : text;
+}
+
+/** Render `rows` as RFC 4180 CSV: a header row, one row per record, `\n` line endings. */
+export function toCsv(rows: ExportRow[]): string {
+  const lines = [COLUMNS.join(","), ...rows.map((row) => COLUMNS.map((column) => csvField(row[column])).join(","))];
+  return lines.join("\n");
+}
+
+/** Render `rows` as pretty-printed (2-space indent) JSON. */
+export function toJson(rows: ExportRow[]): string {
+  return JSON.stringify(rows, null, 2);
+}

package/src/domain/segment-rule.ts

@@ -0,0 +1,10 @@
+/**
+ * A rule that tags a tool execution as belonging to a named segment (e.g.
+ * `review`) when the tool name matches `tool` and the tool's argument text
+ * matches `pattern`.
+ */
+export interface SegmentRule {
+  tag: string;
+  tool: string;
+  pattern: RegExp;
+}

package/src/domain/task-view.ts

@@ -1,5 +1,5 @@
 import { unionMs } from "./intervals.ts";
-import { emptyUsage } from "./work-record.ts";
+import { emptyUsage, finiteOrZero } from "./work-record.ts";
 import type { UsageTotals, WorkRecord, WorkStatus } from "./work-record.ts";
 
 /**
@@ -22,6 +22,17 @@ export interface TaskView {
   orchestrator: WorkRecord;
   subagents: WorkRecord[];
   usage: UsageTotals;
+  /** Who this task is billed to, from the orchestrator record only — subagent children do not carry their own. */
+  client?: string;
+  /** pi's session display name, from the orchestrator record. */
+  sessionName?: string;
+  /**
+   * Per-tag total milliseconds across the orchestrator and every subagent,
+   * summed rather than unioned: unlike `wallMs`, segment intervals are not
+   * persisted on disk, so once a record settles its per-tag total is all
+   * that remains, and there is nothing left to union across records.
+   */
+  segments: Record<string, number>;
 }
 
 /** One or more tasks grouped by their pi session, with the same union rule. */
@@ -35,20 +46,39 @@ export interface SessionView {
   workMs: number;
   tasks: TaskView[];
   usage: UsageTotals;
+  /** Per-tag total milliseconds summed across the session's tasks. See {@link TaskView.segments}. */
+  segments: Record<string, number>;
 }
 
 function toMs(iso: string): number {
   return Date.parse(iso);
 }
 
-function sumUsage(totals: UsageTotals[]): UsageTotals {
+/** Sum per-tag milliseconds across several segment maps (older records without one count as `{}`). */
+function sumSegments(segmentMaps: Array<Record<string, number> | undefined>): Record<string, number> {
+  const result: Record<string, number> = {};
+  for (const segments of segmentMaps) {
+    for (const [tag, ms] of Object.entries(segments ?? {})) {
+      result[tag] = (result[tag] ?? 0) + ms;
+    }
+  }
+  return result;
+}
+
+/**
+ * Sum several {@link UsageTotals}, tolerating a missing entry (a record
+ * without a `usage` field) and missing or non-finite numeric fields on an
+ * entry — both treated as zero rather than corrupting the sum with
+ * `undefined`/`NaN`.
+ */
+export function sumUsage(totals: Array<UsageTotals | undefined>): UsageTotals {
   const usage = emptyUsage();
   for (const total of totals) {
-    usage.input += total.input;
-    usage.output += total.output;
-    usage.cacheRead += total.cacheRead;
-    usage.cacheWrite += total.cacheWrite;
-    usage.cost += total.cost;
+    usage.input += finiteOrZero(total?.input);
+    usage.output += finiteOrZero(total?.output);
+    usage.cacheRead += finiteOrZero(total?.cacheRead);
+    usage.cacheWrite += finiteOrZero(total?.cacheWrite);
+    usage.cost += finiteOrZero(total?.cost);
   }
   return usage;
 }
@@ -117,10 +147,13 @@ function buildTaskView(orchestrator: WorkRecord, subagents: WorkRecord[]): TaskV
   const waitingMs = orchestrator.waitingMs;
   const workMs = wallMs - waitingMs;
   const usage = sumUsage([orchestrator.usage, ...subagents.map((child) => child.usage)]);
+  const segments = sumSegments([orchestrator.segments, ...subagents.map((child) => child.segments)]);
 
   return {
     id: orchestrator.id,
     ...(orchestrator.sessionId !== undefined ? { sessionId: orchestrator.sessionId } : {}),
+    ...(orchestrator.client !== undefined ? { client: orchestrator.client } : {}),
+    ...(orchestrator.sessionName !== undefined ? { sessionName: orchestrator.sessionName } : {}),
     project: orchestrator.project,
     prompt: orchestrator.prompt,
     startedAt: orchestrator.startedAt,
@@ -132,6 +165,7 @@ function buildTaskView(orchestrator: WorkRecord, subagents: WorkRecord[]): TaskV
     orchestrator,
     subagents,
     usage,
+    segments,
   };
 }
 
@@ -182,6 +216,7 @@ export function buildSessions(tasks: TaskView[]): SessionView[] {
     const startedAtMs = Math.min(...sessionTasks.map((task) => toMs(task.startedAt)));
     const endedAtMs = Math.max(...sessionTasks.map((task) => toMs(task.endedAt)));
     const usage = sumUsage(sessionTasks.map((task) => task.usage));
+    const segments = sumSegments(sessionTasks.map((task) => task.segments));
 
     sessions.push({
       sessionId,
@@ -193,6 +228,7 @@ export function buildSessions(tasks: TaskView[]): SessionView[] {
       workMs,
       tasks: sessionTasks,
       usage,
+      segments,
     });
   }
 

package/src/domain/work-record.ts

@@ -38,6 +38,13 @@ export interface WorkRecordCore {
   turns: number;
   tools: Record<string, number>;
   subagents: SubagentSpan[];
+  /**
+   * Union milliseconds per tag spent in tool calls matched by a
+   * {@link SegmentRule} (e.g. `review`). Optional so older persisted
+   * records without this field still satisfy the type; callers reading
+   * from disk should treat a missing value as `{}`.
+   */
+  segments?: Record<string, number>;
   usage: UsageTotals;
   status: WorkStatus;
 }
@@ -52,6 +59,10 @@ export interface WorkRecordMetadata {
   sessionFile?: string;
   mode?: string;
   model?: string;
+  /** Who this work is billed to. See {@link resolveClient} in `client-label.ts`. */
+  client?: string;
+  /** pi's session display name at the time this record settled. */
+  sessionName?: string;
 }
 
 export type WorkRecord = WorkRecordCore & WorkRecordMetadata;
@@ -59,3 +70,46 @@ export type WorkRecord = WorkRecordCore & WorkRecordMetadata;
 export function emptyUsage(): UsageTotals {
   return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 };
 }
+
+/** A finite number, or `0` for `undefined`/`NaN`/`Infinity`/non-numbers. */
+export function finiteOrZero(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+
+const ROLES = new Set<WorkRole>(["orchestrator", "subagent"]);
+const STATUSES = new Set<WorkStatus>(["completed", "aborted", "interrupted"]);
+
+/**
+ * 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
+ * record from an incompatible schema does not crash task/session views.
+ */
+export function isWorkRecord(value: unknown): value is WorkRecord {
+  if (!value || typeof value !== "object") return false;
+  const record = value as Record<string, unknown>;
+
+  return (
+    typeof record["schema"] === "number" &&
+    typeof record["id"] === "string" &&
+    ROLES.has(record["role"] as WorkRole) &&
+    typeof record["pid"] === "number" &&
+    typeof record["parentPid"] === "number" &&
+    typeof record["project"] === "string" &&
+    typeof record["prompt"] === "string" &&
+    typeof record["startedAt"] === "string" &&
+    typeof record["settledAt"] === "string" &&
+    Number.isFinite(record["wallMs"]) &&
+    Number.isFinite(record["waitingMs"]) &&
+    Number.isFinite(record["workMs"]) &&
+    typeof record["runs"] === "number" &&
+    typeof record["turns"] === "number" &&
+    typeof record["tools"] === "object" &&
+    record["tools"] !== null &&
+    Array.isArray(record["subagents"]) &&
+    typeof record["usage"] === "object" &&
+    record["usage"] !== null &&
+    STATUSES.has(record["status"] as WorkStatus) &&
+    (record["client"] === undefined || typeof record["client"] === "string") &&
+    (record["sessionName"] === undefined || typeof record["sessionName"] === "string")
+  );
+}

package/src/domain/work-tracker.ts

@@ -1,13 +1,16 @@
 import { randomUUID } from "node:crypto";
 import type { Clock } from "../ports/clock.ts";
 import { clampIntervals, unionMs } from "./intervals.ts";
-import { emptyUsage, WORK_RECORD_SCHEMA } from "./work-record.ts";
+import { emptyUsage, finiteOrZero, WORK_RECORD_SCHEMA } from "./work-record.ts";
 import type { SubagentSpan, UsageTotals, WorkRecordCore, WorkStatus } from "./work-record.ts";
+import type { SegmentRule } from "./segment-rule.ts";
 
 export interface WorkTrackerOptions {
   clock: Clock;
   interactiveTools: string[];
   subagentTool: string;
+  /** Rules that tag a tool execution's span under a named segment. Defaults to none. */
+  segmentRules?: SegmentRule[];
 }
 
 interface Interval {
@@ -23,6 +26,8 @@ interface OpenSubagentSpan {
 }
 
 interface RunState {
+  /** Generated once when the run opens, so it stays stable across `peek` and the final `onSettled`/`onShutdown`. */
+  id: string;
   startedAt: number;
   prompt: string;
   runs: number;
@@ -35,6 +40,14 @@ interface RunState {
   openToolWaits: Map<string, Interval>;
   subagents: SubagentSpan[];
   openSubagents: Map<string, OpenSubagentSpan>;
+  /**
+   * Segment spans opened by a matching {@link SegmentRule}, keyed by tag.
+   * A `Map` rather than a plain object so a tag such as `__proto__` cannot
+   * pollute the object prototype while the run is in progress.
+   */
+  segmentSpans: Map<string, Interval[]>;
+  /** The still-open segment span for a tool call id, if any. */
+  openSegments: Map<string, Interval>;
 }
 
 interface RunEndMessage {
@@ -51,17 +64,20 @@ export class WorkTracker {
   private readonly clock: Clock;
   private readonly interactiveTools: Set<string>;
   private readonly subagentTool: string;
+  private readonly segmentRules: SegmentRule[];
   private state: RunState | undefined;
 
   constructor(options: WorkTrackerOptions) {
     this.clock = options.clock;
     this.interactiveTools = new Set(options.interactiveTools);
     this.subagentTool = options.subagentTool;
+    this.segmentRules = options.segmentRules ?? [];
   }
 
   onRunStart(prompt: string): void {
     if (!this.state) {
       this.state = {
+        id: randomUUID(),
         startedAt: this.clock.now(),
         prompt,
         runs: 1,
@@ -73,6 +89,8 @@ export class WorkTracker {
         openToolWaits: new Map(),
         subagents: [],
         openSubagents: new Map(),
+        segmentSpans: new Map(),
+        openSegments: new Map(),
       };
       return;
     }
@@ -83,17 +101,26 @@ export class WorkTracker {
     if (!this.state) return;
     this.state.turns++;
     if (!usage) return;
-    this.state.usage.input += usage.input ?? 0;
-    this.state.usage.output += usage.output ?? 0;
-    this.state.usage.cacheRead += usage.cacheRead ?? 0;
-    this.state.usage.cacheWrite += usage.cacheWrite ?? 0;
-    this.state.usage.cost += usage.cost ?? 0;
+    this.state.usage.input += finiteOrZero(usage.input);
+    this.state.usage.output += finiteOrZero(usage.output);
+    this.state.usage.cacheRead += finiteOrZero(usage.cacheRead);
+    this.state.usage.cacheWrite += finiteOrZero(usage.cacheWrite);
+    this.state.usage.cost += finiteOrZero(usage.cost);
   }
 
   onToolStart(toolCallId: string, toolName: string, args: Record<string, unknown> | undefined): void {
     if (!this.state) return;
     this.state.tools[toolName] = (this.state.tools[toolName] ?? 0) + 1;
 
+    const rule = this.segmentRules.find((candidate) => candidate.tool === toolName && candidate.pattern.test(segmentText(args)));
+    if (rule) {
+      const span: Interval = { start: this.clock.now(), end: undefined };
+      const spans = this.state.segmentSpans.get(rule.tag) ?? [];
+      spans.push(span);
+      this.state.segmentSpans.set(rule.tag, spans);
+      this.state.openSegments.set(toolCallId, span);
+    }
+
     if (this.interactiveTools.has(toolName)) {
       const span: Interval = { start: this.clock.now(), end: undefined };
       this.state.waitingSpans.push(span);
@@ -116,6 +143,12 @@ export class WorkTracker {
   onToolEnd(toolCallId: string, result: unknown): void {
     if (!this.state) return;
 
+    const openSegment = this.state.openSegments.get(toolCallId);
+    if (openSegment) {
+      this.state.openSegments.delete(toolCallId);
+      openSegment.end = this.clock.now();
+    }
+
     const openSubagent = this.state.openSubagents.get(toolCallId);
     if (openSubagent) {
       this.state.openSubagents.delete(toolCallId);
@@ -164,39 +197,59 @@ export class WorkTracker {
 
   onSettled(): WorkRecordCore | undefined {
     if (!this.state) return undefined;
-    const record = this.finalize(this.state.status);
+    const record = this.buildRecord(this.state.status, this.clock.now());
     this.state = undefined;
     return record;
   }
 
   onShutdown(): WorkRecordCore | undefined {
     if (!this.state) return undefined;
-    const record = this.finalize("interrupted");
+    const record = this.buildRecord("interrupted", this.clock.now());
     this.state = undefined;
     return record;
   }
 
-  private finalize(status: WorkStatus): WorkRecordCore {
+  /**
+   * Returns what {@link onSettled}/{@link onShutdown} would produce right
+   * now, without mutating any state: open spans are truncated only in the
+   * returned snapshot, so the tracker keeps running unaffected and a later
+   * `peek` or the eventual settle still sees the spans' true open-ended
+   * state. `undefined` when idle. The returned `id` matches the id the
+   * eventual settled record will carry, since both are generated once
+   * in {@link onRunStart}.
+   */
+  peek(status: WorkStatus): WorkRecordCore | undefined {
+    if (!this.state) return undefined;
+    return this.buildRecord(status, this.clock.now());
+  }
+
+  private buildRecord(status: WorkStatus, settledAt: number): WorkRecordCore {
     const state = this.state;
     if (!state) {
-      throw new Error("finalize called without an open run");
+      throw new Error("buildRecord called without an open run");
     }
-    const settledAt = this.clock.now();
     const wallMs = settledAt - state.startedAt;
 
-    for (const span of state.waitingSpans) {
-      if (span.end === undefined) {
-        span.end = settledAt;
-      }
-    }
-
-    const closedSpans = state.waitingSpans.map((span) => ({ start: span.start, end: span.end as number }));
+    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 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));
+      if (tagMs > 0) {
+        segmentEntries.push([tag, tagMs]);
+      }
+    }
+    // Built via Object.fromEntries (never `segments[tag] = ...`) so a tag
+    // such as `__proto__` becomes an own data property instead of silently
+    // repointing the object's prototype.
+    const segments = Object.fromEntries(segmentEntries);
+
     return {
       schema: WORK_RECORD_SCHEMA,
-      id: randomUUID(),
+      id: state.id,
       prompt: state.prompt,
       startedAt: new Date(state.startedAt).toISOString(),
       settledAt: new Date(settledAt).toISOString(),
@@ -207,12 +260,19 @@ export class WorkTracker {
       turns: state.turns,
       tools: state.tools,
       subagents: state.subagents,
+      segments,
       usage: state.usage,
       status,
     };
   }
 }
 
+/** Text to match a {@link SegmentRule} pattern against: the `command` string arg when present, else the whole args object as JSON. */
+function segmentText(args: Record<string, unknown> | undefined): string {
+  const command = args?.["command"];
+  return typeof command === "string" ? command : JSON.stringify(args ?? {});
+}
+
 function extractTaskId(result: unknown): string | undefined {
   if (!result || typeof result !== "object") return undefined;
   const details = (result as { details?: unknown }).details;