kankaku 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 soyunninja
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,156 @@
+# kankaku
+
+A [pi](https://pi.dev) extension that measures how long an agent actually
+spends working on each prompt, so the time can later be accounted for
+(billing, reporting).
+
+## What it measures
+
+For every prompt, kankaku tracks the span from `before_agent_start` to
+`agent_settled` (or to `session_shutdown` if pi exits mid-run) and splits it
+into:
+
+- **`waitingMs`**: time pi spent blocked on the user — the union of
+  `ui_prompt_start/end` spans and the execution spans of configured
+  interactive tools (default `ask_user_question`, `ask_user_choice`). Union
+  avoids double-counting when a tool internally triggers a UI prompt.
+- **`workMs`**: `wallMs - waitingMs`, the actual work time.
+
+Every pi process — the orchestrator and any subagent child spawned by
+`subagent_run` — records its own prompt-to-idle spans, tagged with a `role`
+(`orchestrator` or `subagent`) and its `pid`/`parentPid`, so records can be
+joined later.
+
+## Install
+
+kankaku is a pi package. Pick one source:
+
+```
+pi install npm:kankaku                          # from npm
+pi install git:github.com/soyunninja/kankaku    # from git (add @v0.1.0 to pin)
+pi install /absolute/path/to/kankaku            # local checkout, no copy
+```
+
+`pi install` writes to your global `~/.pi/agent/settings.json`, so the
+extension loads in every pi process, including the subagent children that
+`subagent_run` spawns. Use `-l` to install into a project's `.pi/settings.json`
+instead; note that project-local resources load only after the project is
+trusted, which a subagent child may not inherit.
+
+To try it without installing: `pi -e /absolute/path/to/kankaku`.
+
+## Record schema
+
+Each line in `worklog.jsonl` is one JSON object:
+
+```json
+{
+  "schema": 1,
+  "id": "uuid",
+  "role": "orchestrator",
+  "pid": 4242,
+  "parentPid": 4000,
+  "project": "/abs/project/path",
+  "sessionId": "…",
+  "sessionFile": "…",
+  "mode": "tui",
+  "model": "anthropic/claude-opus",
+  "prompt": "first 200 chars of the first prompt",
+  "startedAt": "2026-09-10T16:00:00.000Z",
+  "settledAt": "2026-09-10T16:04:10.000Z",
+  "wallMs": 250000,
+  "waitingMs": 30000,
+  "workMs": 220000,
+  "runs": 2,
+  "turns": 9,
+  "tools": { "bash": 4, "read": 3, "subagent_run": 1, "ask_user_question": 1 },
+  "subagents": [{ "toolCallId": "…", "agent": "sdd-explore", "mode": "task", "taskId": "t1", "ms": 90000 }],
+  "usage": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0, "cost": 0 },
+  "status": "completed"
+}
+```
+
+`status` is one of `completed`, `aborted` (the last assistant message had
+`stopReason: "aborted"`), or `interrupted` (pi shut down while still
+running).
+
+## Task and session views
+
+Each `WorkRecord` still measures one pi process's own prompt-to-idle span.
+But a `subagent_run` in `background` mode returns immediately while its
+child process keeps working, so the orchestrator's own `wallMs` can
+under-report how long the task actually took. Two derived, read-only views
+correct for that, built purely from `pid`/`parentPid`/`startedAt`/`settledAt`
+already present on every record — no new fields are persisted to
+`worklog.jsonl`.
+
+- **Task**: one orchestrator record plus every subagent record matched to
+  it — same `project`, `parentPid === orchestrator.pid`, and the child's
+  `startedAt` falling inside the orchestrator's `[startedAt, settledAt]`
+  window. (If a pid is reused across runs and several orchestrator records
+  match, the child attaches to the latest-starting one.) A task's `wallMs`
+  is the **union** of the orchestrator's interval and every matched child's
+  interval — never their sum — so parallel background children are not
+  double-counted, and a child that outlives the orchestrator's own settle
+  time correctly extends the task's span. `waitingMs` is the orchestrator's
+  own waiting time, `workMs = wallMs - waitingMs`, and `usage` is the sum of
+  the orchestrator's and every child's token/cost totals.
+- **Session**: tasks grouped by `sessionId` (tasks with no `sessionId` are
+  grouped under `"unknown"`). A session's `wallMs` is the union of every
+  interval — orchestrator and subagent alike — across all of its tasks;
+  `waitingMs` is the sum of each task's `waitingMs`, and `workMs = wallMs -
+  waitingMs`.
+- **Orphan subagents**: a subagent record with no matching orchestrator
+  record (for example, its parent's record was lost, or it belongs to a
+  different project) is excluded from every task but is not silently
+  dropped — it stays visible so gaps in the log are noticeable rather than
+  hidden.
+
+## The `/kankaku` command
+
+Run `/kankaku` inside pi to see today's totals (work, waiting, record count)
+per role, plus a union-based tasks segment. In the interactive TUI the report
+is appended to the chat transcript as a durable card that is never sent to
+the LLM; without a UI (print or RPC mode) it falls back to a notification.
+Arguments are whitespace-separated and order-insensitive:
+
+- `/kankaku` — today's role totals and tasks segment, each with its estimated cost.
+- `/kankaku all` — same, but across every record.
+- `/kankaku tasks` — one line per task (time, union wall/work, cost,
+  subagent count, truncated prompt) for the **current pi session**. Add `all` for
+  every session. If the current session has no `sessionId`, tasks from every
+  session are shown instead.
+- `/kankaku sessions` — one line per session (id, time range, union
+  wall/work, cost, task count) for today. Add `all` for every day.
+
+Cost figures are the sum of `usage.cost` as priced by pi's model table
+(per-million-token rates in `models.json`, adjustable with `modelOverrides`).
+For subscription-based providers this is an estimate at API list prices, not
+an invoice.
+
+While an agent is running, pi's status bar shows a `⏱ mm:ss` indicator with
+the elapsed time for the current run.
+
+## Environment variables
+
+- `KANKAKU_DIR`: directory for the work log, relative to the project cwd
+  unless given as an absolute path. Defaults to `.kankaku`.
+- `KANKAKU_INTERACTIVE_TOOLS`: comma-separated list of tool names whose
+  execution span counts as waiting time. Defaults to
+  `ask_user_question,ask_user_choice`.
+
+## Limitations
+
+- A prompt shown by a tool that does not go through `ctx.ui` and is not
+  listed in `KANKAKU_INTERACTIVE_TOOLS` counts as work, not waiting time.
+- Subagent totals are reported separately in the per-role summary and are
+  **not** summed into the orchestrator's `wallMs` there: task-mode subagents
+  run inside the parent's wall clock, and background subagents can outlive
+  the parent's idle moment, so naively adding them would double-count or
+  misrepresent billable time. Use the task/session views above (union-based,
+  never a sum) for a correct combined figure.
+
+## Roadmap
+
+- Remote sync service: the `id` and `schema` fields are already in place for
+  a future `synced` cursor that uploads records to a remote store.

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "kankaku",
+  "version": "0.1.0",
+  "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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/soyunninja/kankaku.git"
+  },
+  "homepage": "https://github.com/soyunninja/kankaku#readme",
+  "bugs": {
+    "url": "https://github.com/soyunninja/kankaku/issues"
+  },
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "time-tracking",
+    "agents"
+  ],
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/extension.ts"
+    ]
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "check": "npm run typecheck && npm test",
+    "prepublishOnly": "npm run check"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.85.1",
+    "@earendil-works/pi-tui": "^0.85.1",
+    "@types/node": "^24.13.4",
+    "typescript": "^5.7.0"
+  }
+}

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

@@ -0,0 +1,44 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { WorkLog } from "../ports/work-log.ts";
+import type { WorkRecord } from "../domain/work-record.ts";
+
+const LOG_FILE_NAME = "worklog.jsonl";
+
+/**
+ * Append-only JSONL {@link WorkLog} backed by `<dir>/worklog.jsonl`.
+ * A record is written with a single `appendFileSync` call so a parent and
+ * its subagent children can write concurrently without interleaving lines.
+ */
+export class JsonlWorkLog implements WorkLog {
+  private readonly dir: string;
+
+  constructor(dir: string) {
+    this.dir = dir;
+  }
+
+  private get filePath(): string {
+    return join(this.dir, LOG_FILE_NAME);
+  }
+
+  append(record: WorkRecord): void {
+    mkdirSync(this.dir, { recursive: true });
+    appendFileSync(this.filePath, `${JSON.stringify(record)}\n`);
+  }
+
+  readAll(): WorkRecord[] {
+    if (!existsSync(this.filePath)) return [];
+    const content = readFileSync(this.filePath, "utf8");
+    const records: WorkRecord[] = [];
+    for (const line of content.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      try {
+        records.push(JSON.parse(trimmed) as WorkRecord);
+      } catch {
+        // Tolerate malformed lines (e.g. a torn write); skip them.
+      }
+    }
+    return records;
+  }
+}

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

@@ -0,0 +1,36 @@
+import { isAbsolute, join } from "node:path";
+import type { WorkRecord } from "../domain/work-record.ts";
+import type { WorkLog } from "../ports/work-log.ts";
+import { JsonlWorkLog } from "./jsonl-work-log.ts";
+
+/**
+ * {@link WorkLog} that resolves a relative log directory lazily: against the
+ * project of the first appended record, or against `fallbackCwd()` when a
+ * read happens before any record was written in this process.
+ */
+export class LazyJsonlWorkLog implements WorkLog {
+  private readonly dirOrRelative: string;
+  private readonly fallbackCwd: () => string;
+  private resolved: JsonlWorkLog | undefined;
+
+  constructor(dirOrRelative: string, fallbackCwd: () => string = () => process.cwd()) {
+    this.dirOrRelative = dirOrRelative;
+    this.fallbackCwd = fallbackCwd;
+  }
+
+  private resolveFor(cwd: string): JsonlWorkLog {
+    if (!this.resolved) {
+      const dir = isAbsolute(this.dirOrRelative) ? this.dirOrRelative : join(cwd, this.dirOrRelative);
+      this.resolved = new JsonlWorkLog(dir);
+    }
+    return this.resolved;
+  }
+
+  append(record: WorkRecord): void {
+    this.resolveFor(record.project).append(record);
+  }
+
+  readAll(): WorkRecord[] {
+    return this.resolveFor(this.fallbackCwd()).readAll();
+  }
+}

package/src/adapters/pi-tracker.ts

@@ -0,0 +1,243 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Box, Text } from "@earendil-works/pi-tui";
+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 { WorkLog } from "../ports/work-log.ts";
+import { formatReport, formatSessions, formatTasks, localDay, summarize } from "./report.ts";
+
+export interface PiTrackerDeps {
+  tracker: WorkTracker;
+  log: WorkLog;
+  role: WorkRole;
+  pid: number;
+  parentPid: number;
+  /** Status line refresh interval in ms. Defaults to 1000. */
+  statusIntervalMs?: number;
+}
+
+const STATUS_KEY = "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[];
+}
+
+function formatElapsed(ms: number): 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")}`;
+}
+
+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) => {
+    try {
+      fn(event, ctx);
+    } catch (error) {
+      notifyError(ctx, error);
+    }
+  };
+}
+
+/**
+ * Wires pi lifecycle events to a {@link WorkTracker}, persisting finished
+ * 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 statusIntervalMs = deps.statusIntervalMs ?? 1000;
+
+  let runStartedAt: number | undefined;
+  let statusTimer: NodeJS.Timeout | undefined;
+
+  function stopStatus(ctx: ExtensionContext): void {
+    if (statusTimer) {
+      clearInterval(statusTimer);
+      statusTimer = undefined;
+    }
+    if (ctx.hasUI) {
+      ctx.ui.setStatus(STATUS_KEY, undefined);
+    }
+    runStartedAt = undefined;
+  }
+
+  function startStatus(ctx: ExtensionContext): void {
+    if (!ctx.hasUI) return;
+    runStartedAt = Date.now();
+    ctx.ui.setStatus(STATUS_KEY, formatElapsed(0));
+    statusTimer = setInterval(() => {
+      if (runStartedAt === undefined) return;
+      ctx.ui.setStatus(STATUS_KEY, formatElapsed(Date.now() - runStartedAt));
+    }, statusIntervalMs);
+    statusTimer.unref?.();
+  }
+
+  function buildRecord(core: NonNullable<ReturnType<WorkTracker["onSettled"]>>, ctx: ExtensionContext): WorkRecord {
+    const model = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined;
+    return {
+      ...core,
+      role,
+      pid,
+      parentPid,
+      project: ctx.cwd,
+      sessionId: ctx.sessionManager.getSessionId(),
+      sessionFile: ctx.sessionManager.getSessionFile(),
+      mode: ctx.mode,
+      ...(model !== undefined ? { model } : {}),
+    };
+  }
+
+  pi.on(
+    "before_agent_start",
+    guarded((event, ctx) => {
+      tracker.onRunStart(event.prompt);
+      if (runStartedAt === undefined) startStatus(ctx);
+    }),
+  );
+
+  pi.on(
+    "agent_end",
+    guarded((event) => {
+      tracker.onRunEnd(event.messages);
+    }),
+  );
+
+  pi.on(
+    "turn_end",
+    guarded((event) => {
+      const message = event.message;
+      const usage = message && "usage" in message ? message.usage : undefined;
+      tracker.onTurnEnd(
+        usage
+          ? {
+              input: usage.input,
+              output: usage.output,
+              cacheRead: usage.cacheRead,
+              cacheWrite: usage.cacheWrite,
+              cost: usage.cost.total,
+            }
+          : undefined,
+      );
+    }),
+  );
+
+  pi.on(
+    "tool_execution_start",
+    guarded((event) => {
+      tracker.onToolStart(event.toolCallId, event.toolName, event.args);
+    }),
+  );
+
+  pi.on(
+    "tool_execution_end",
+    guarded((event) => {
+      tracker.onToolEnd(event.toolCallId, event.result);
+    }),
+  );
+
+  pi.on(
+    "ui_prompt_start",
+    guarded((event) => {
+      tracker.onUiPromptStart(event.kind);
+    }),
+  );
+
+  pi.on(
+    "ui_prompt_end",
+    guarded((event) => {
+      tracker.onUiPromptEnd(event.kind);
+    }),
+  );
+
+  pi.on(
+    "agent_settled",
+    guarded((_event, ctx) => {
+      const core = tracker.onSettled();
+      if (core) {
+        log.append(buildRecord(core, ctx));
+      }
+      stopStatus(ctx);
+    }),
+  );
+
+  pi.on(
+    "session_shutdown",
+    guarded((_event, ctx) => {
+      const core = tracker.onShutdown();
+      if (core) {
+        log.append(buildRecord(core, ctx));
+      }
+      stopStatus(ctx);
+    }),
+  );
+
+  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")}`);
+  }
+
+  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.",
+    handler: async (args, ctx) => {
+      try {
+        const tokens = args.trim().split(/\s+/).filter(Boolean);
+        const all = tokens.includes("all");
+        const records = log.readAll();
+        const today = localDay(new Date().toISOString());
+
+        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

@@ -0,0 +1,133 @@
+import { buildTasks } from "../domain/task-view.ts";
+import type { SessionView, TaskView } from "../domain/task-view.ts";
+import type { WorkRecord, WorkRole } from "../domain/work-record.ts";
+
+export interface RoleTotals {
+  workMs: number;
+  waitingMs: number;
+  wallMs: number;
+  count: number;
+  /** Estimated cost in USD, as priced by pi's model table. */
+  cost: number;
+}
+
+export interface TaskTotals {
+  count: number;
+  wallMs: number;
+  workMs: number;
+  /** Estimated cost in USD, orchestrator and subagents combined. */
+  cost: number;
+}
+
+export type Summary = Record<WorkRole, RoleTotals> & { tasks: TaskTotals };
+
+export interface SummarizeOptions {
+  /** Local day in `YYYY-MM-DD` format. Defaults to today when `all` is not set. */
+  day?: string;
+  /** Include every record regardless of day. */
+  all?: boolean;
+}
+
+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 };
+}
+
+/**
+ * Aggregate work records by role, restricted to one local day unless `all`
+ * is set. Also computes a `tasks` segment (union-based `wallMs`/`workMs`
+ * over one orchestrator run and its subagents) for tasks whose `startedAt`
+ * falls on the same day.
+ */
+export function summarize(records: WorkRecord[], options: SummarizeOptions): Summary {
+  const targetDay = options.all ? undefined : (options.day ?? localDay(new Date().toISOString()));
+
+  const summary: Summary = {
+    orchestrator: emptyTotals(),
+    subagent: emptyTotals(),
+    tasks: { count: 0, wallMs: 0, workMs: 0, cost: 0 },
+  };
+
+  for (const record of records) {
+    if (targetDay !== undefined && localDay(record.startedAt) !== targetDay) continue;
+    const totals = summary[record.role];
+    totals.workMs += record.workMs;
+    totals.waitingMs += record.waitingMs;
+    totals.wallMs += record.wallMs;
+    totals.count += 1;
+    totals.cost += record.usage.cost;
+  }
+
+  const tasks = buildTasks(records).filter((task) => targetDay === undefined || localDay(task.startedAt) === targetDay);
+  for (const task of tasks) {
+    summary.tasks.count += 1;
+    summary.tasks.wallMs += task.wallMs;
+    summary.tasks.workMs += task.workMs;
+    summary.tasks.cost += task.usage.cost;
+  }
+
+  return summary;
+}
+
+function formatMinutes(ms: number): string {
+  const totalSeconds = Math.round(ms / 1000);
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  return `${minutes}m${String(seconds).padStart(2, "0")}s`;
+}
+
+/** Estimated USD cost with two decimals, e.g. `$1.23`. */
+function formatCost(cost: number): string {
+  return `$${cost.toFixed(2)}`;
+}
+
+function formatTime(iso: string): string {
+  const date = new Date(iso);
+  const hours = String(date.getHours()).padStart(2, "0");
+  const minutes = String(date.getMinutes()).padStart(2, "0");
+  return `${hours}:${minutes}`;
+}
+
+/** Render a short, human-readable summary for the `/kankaku` command. */
+export function formatReport(summary: Summary): string {
+  const lines = ROLES.map((role) => {
+    const totals = summary[role];
+    return `${role}: work ${formatMinutes(totals.workMs)}, waiting ${formatMinutes(totals.waitingMs)}, ${totals.count} record(s), ${formatCost(totals.cost)}`;
+  });
+  lines.push(
+    `tasks: ${summary.tasks.count}, wall ${formatMinutes(summary.tasks.wallMs)}, work ${formatMinutes(summary.tasks.workMs)}, ${formatCost(summary.tasks.cost)}`,
+  );
+  return lines.join(" | ");
+}
+
+/** Render one line per task: time, union-based wall/work, cost, 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}`;
+    })
+    .join("\n");
+}
+
+/** Render one line per session: truncated id, time range, union-based wall/work, cost, 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}`,
+    )
+    .join("\n");
+}

package/src/config.ts

@@ -0,0 +1,33 @@
+export interface KankakuConfig {
+  /** Directory for the work log, relative to the project cwd unless absolute. */
+  dir: string;
+  /** Tool names whose execution span counts as waiting time. */
+  interactiveTools: string[];
+  /** Tool name used to run subagents. */
+  subagentTool: string;
+}
+
+const DEFAULT_DIR = ".kankaku";
+const DEFAULT_INTERACTIVE_TOOLS = ["ask_user_question", "ask_user_choice"];
+const SUBAGENT_TOOL = "subagent_run";
+
+export function loadConfig(env: NodeJS.ProcessEnv = process.env): KankakuConfig {
+  const dir = env["KANKAKU_DIR"]?.trim() || DEFAULT_DIR;
+  const interactiveToolsRaw = env["KANKAKU_INTERACTIVE_TOOLS"]?.trim();
+  const interactiveTools = interactiveToolsRaw
+    ? interactiveToolsRaw
+        .split(",")
+        .map((tool) => tool.trim())
+        .filter((tool) => tool.length > 0)
+    : DEFAULT_INTERACTIVE_TOOLS;
+
+  return {
+    dir,
+    interactiveTools,
+    subagentTool: SUBAGENT_TOOL,
+  };
+}
+
+export function detectRole(env: NodeJS.ProcessEnv = process.env): "orchestrator" | "subagent" {
+  return env["GENTLE_PI_AGENTS_CHILD"] === "1" ? "subagent" : "orchestrator";
+}

package/src/domain/intervals.ts

@@ -0,0 +1,53 @@
+export interface Interval {
+  start: number;
+  end: number;
+}
+
+/**
+ * Restrict every interval to `[windowStart, windowEnd]` and drop any that
+ * become empty (or invalid) after clamping.
+ */
+export function clampIntervals(intervals: Interval[], windowStart: number, windowEnd: number): Interval[] {
+  return intervals
+    .map((interval) => ({
+      start: Math.max(interval.start, windowStart),
+      end: Math.min(interval.end, windowEnd),
+    }))
+    .filter((interval) => interval.end > interval.start);
+}
+
+/**
+ * Total duration covered by the union of the given intervals — never the
+ * sum, so overlapping (e.g. parallel subagent) spans are not double-counted.
+ */
+export function unionMs(intervals: Array<{ start: number; end: number }>): number {
+  const sorted = [...intervals].sort((a, b) => a.start - b.start);
+
+  let total = 0;
+  let currentStart: number | undefined;
+  let currentEnd: number | undefined;
+
+  for (const interval of sorted) {
+    if (interval.end <= interval.start) continue;
+
+    if (currentStart === undefined || currentEnd === undefined) {
+      currentStart = interval.start;
+      currentEnd = interval.end;
+      continue;
+    }
+
+    if (interval.start <= currentEnd) {
+      currentEnd = Math.max(currentEnd, interval.end);
+    } else {
+      total += currentEnd - currentStart;
+      currentStart = interval.start;
+      currentEnd = interval.end;
+    }
+  }
+
+  if (currentStart !== undefined && currentEnd !== undefined) {
+    total += currentEnd - currentStart;
+  }
+
+  return total;
+}

package/src/domain/task-view.ts

@@ -0,0 +1,200 @@
+import { unionMs } from "./intervals.ts";
+import { emptyUsage } from "./work-record.ts";
+import type { UsageTotals, WorkRecord, WorkStatus } from "./work-record.ts";
+
+/**
+ * One orchestrator run plus every subagent it spawned, with `wallMs`
+ * recomputed as the union of the orchestrator's span and each child's span
+ * — never their sum — because background children keep running in parallel
+ * after the orchestrator settles.
+ */
+export interface TaskView {
+  id: string;
+  sessionId?: string;
+  project: string;
+  prompt: string;
+  startedAt: string;
+  endedAt: string;
+  wallMs: number;
+  waitingMs: number;
+  workMs: number;
+  status: WorkStatus;
+  orchestrator: WorkRecord;
+  subagents: WorkRecord[];
+  usage: UsageTotals;
+}
+
+/** One or more tasks grouped by their pi session, with the same union rule. */
+export interface SessionView {
+  sessionId: string;
+  project: string;
+  startedAt: string;
+  endedAt: string;
+  wallMs: number;
+  waitingMs: number;
+  workMs: number;
+  tasks: TaskView[];
+  usage: UsageTotals;
+}
+
+function toMs(iso: string): number {
+  return Date.parse(iso);
+}
+
+function sumUsage(totals: UsageTotals[]): 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;
+  }
+  return usage;
+}
+
+/**
+ * Match every subagent record to the orchestrator record it belongs to: same
+ * project, `parentPid === orchestrator.pid`, and the child's `startedAt`
+ * falls inside the orchestrator's `[startedAt, settledAt]` window. When
+ * several orchestrator records match (a reused pid), the latest-starting one
+ * wins. Each child is assigned at most once; unmatched children are orphans.
+ */
+function matchChildren(records: WorkRecord[]): {
+  childrenByOrchestratorId: Map<string, WorkRecord[]>;
+  orphans: WorkRecord[];
+} {
+  const orchestrators = records.filter((record) => record.role === "orchestrator");
+  const subagents = records.filter((record) => record.role === "subagent");
+
+  const childrenByOrchestratorId = new Map<string, WorkRecord[]>();
+  for (const orchestrator of orchestrators) {
+    childrenByOrchestratorId.set(orchestrator.id, []);
+  }
+
+  const orphans: WorkRecord[] = [];
+
+  for (const child of subagents) {
+    const childStart = toMs(child.startedAt);
+    let best: WorkRecord | undefined;
+    let bestStart = Number.NEGATIVE_INFINITY;
+
+    for (const orchestrator of orchestrators) {
+      if (orchestrator.project !== child.project) continue;
+      if (orchestrator.pid !== child.parentPid) continue;
+
+      const parentStart = toMs(orchestrator.startedAt);
+      const parentEnd = toMs(orchestrator.settledAt);
+      if (childStart < parentStart || childStart > parentEnd) continue;
+
+      if (parentStart > bestStart) {
+        bestStart = parentStart;
+        best = orchestrator;
+      }
+    }
+
+    if (best) {
+      childrenByOrchestratorId.get(best.id)!.push(child);
+    } else {
+      orphans.push(child);
+    }
+  }
+
+  return { childrenByOrchestratorId, orphans };
+}
+
+function buildTaskView(orchestrator: WorkRecord, subagents: WorkRecord[]): TaskView {
+  const parentStart = toMs(orchestrator.startedAt);
+  const parentEnd = toMs(orchestrator.settledAt);
+
+  const intervals = [
+    { start: parentStart, end: parentEnd },
+    ...subagents.map((child) => ({ start: toMs(child.startedAt), end: toMs(child.settledAt) })),
+  ];
+  const wallMs = unionMs(intervals);
+
+  const endedAtMs = Math.max(parentEnd, ...subagents.map((child) => toMs(child.settledAt)));
+  const waitingMs = orchestrator.waitingMs;
+  const workMs = wallMs - waitingMs;
+  const usage = sumUsage([orchestrator.usage, ...subagents.map((child) => child.usage)]);
+
+  return {
+    id: orchestrator.id,
+    ...(orchestrator.sessionId !== undefined ? { sessionId: orchestrator.sessionId } : {}),
+    project: orchestrator.project,
+    prompt: orchestrator.prompt,
+    startedAt: orchestrator.startedAt,
+    endedAt: new Date(endedAtMs).toISOString(),
+    wallMs,
+    waitingMs,
+    workMs,
+    status: orchestrator.status,
+    orchestrator,
+    subagents,
+    usage,
+  };
+}
+
+/** Build one {@link TaskView} per orchestrator record, sorted by `startedAt`. */
+export function buildTasks(records: WorkRecord[]): TaskView[] {
+  const orchestrators = records
+    .filter((record) => record.role === "orchestrator")
+    .sort((a, b) => toMs(a.startedAt) - toMs(b.startedAt));
+
+  const { childrenByOrchestratorId } = matchChildren(records);
+
+  return orchestrators.map((orchestrator) => buildTaskView(orchestrator, childrenByOrchestratorId.get(orchestrator.id) ?? []));
+}
+
+/** Subagent records that could not be matched to any orchestrator record. */
+export function orphanSubagents(records: WorkRecord[]): WorkRecord[] {
+  return matchChildren(records).orphans;
+}
+
+/**
+ * Group tasks by `sessionId` (tasks without one fall under `"unknown"`).
+ * `wallMs` is the union of every interval — orchestrator and subagent alike
+ * — across all of the session's tasks, not a sum of per-task `wallMs`.
+ */
+export function buildSessions(tasks: TaskView[]): SessionView[] {
+  const groups = new Map<string, TaskView[]>();
+  for (const task of tasks) {
+    const key = task.sessionId ?? "unknown";
+    const list = groups.get(key);
+    if (list) {
+      list.push(task);
+    } else {
+      groups.set(key, [task]);
+    }
+  }
+
+  const sessions: SessionView[] = [];
+
+  for (const [sessionId, sessionTasks] of groups) {
+    const intervals = sessionTasks.flatMap((task) => [
+      { start: toMs(task.orchestrator.startedAt), end: toMs(task.orchestrator.settledAt) },
+      ...task.subagents.map((child) => ({ start: toMs(child.startedAt), end: toMs(child.settledAt) })),
+    ]);
+
+    const wallMs = unionMs(intervals);
+    const waitingMs = sessionTasks.reduce((sum, task) => sum + task.waitingMs, 0);
+    const workMs = wallMs - waitingMs;
+    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));
+
+    sessions.push({
+      sessionId,
+      project: sessionTasks[0]!.project,
+      startedAt: new Date(startedAtMs).toISOString(),
+      endedAt: new Date(endedAtMs).toISOString(),
+      wallMs,
+      waitingMs,
+      workMs,
+      tasks: sessionTasks,
+      usage,
+    });
+  }
+
+  return sessions.sort((a, b) => toMs(a.startedAt) - toMs(b.startedAt));
+}

package/src/domain/work-record.ts

@@ -0,0 +1,61 @@
+/** Current schema version for {@link WorkRecord}. */
+export const WORK_RECORD_SCHEMA = 1;
+
+export type WorkRole = "orchestrator" | "subagent";
+
+export type WorkStatus = "completed" | "aborted" | "interrupted";
+
+export interface UsageTotals {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  cost: number;
+}
+
+export interface SubagentSpan {
+  toolCallId: string;
+  agent: string;
+  mode: string;
+  taskId?: string;
+  ms: number;
+}
+
+/**
+ * Fields the pure {@link WorkTracker} state machine can compute on its own,
+ * with no knowledge of the pi process or session it runs in.
+ */
+export interface WorkRecordCore {
+  schema: number;
+  id: string;
+  prompt: string;
+  startedAt: string;
+  settledAt: string;
+  wallMs: number;
+  waitingMs: number;
+  workMs: number;
+  runs: number;
+  turns: number;
+  tools: Record<string, number>;
+  subagents: SubagentSpan[];
+  usage: UsageTotals;
+  status: WorkStatus;
+}
+
+/** Process/session metadata the adapter layer attaches before persisting a record. */
+export interface WorkRecordMetadata {
+  role: WorkRole;
+  pid: number;
+  parentPid: number;
+  project: string;
+  sessionId?: string;
+  sessionFile?: string;
+  mode?: string;
+  model?: string;
+}
+
+export type WorkRecord = WorkRecordCore & WorkRecordMetadata;
+
+export function emptyUsage(): UsageTotals {
+  return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 };
+}

package/src/domain/work-tracker.ts

@@ -0,0 +1,224 @@
+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 type { SubagentSpan, UsageTotals, WorkRecordCore, WorkStatus } from "./work-record.ts";
+
+export interface WorkTrackerOptions {
+  clock: Clock;
+  interactiveTools: string[];
+  subagentTool: string;
+}
+
+interface Interval {
+  start: number;
+  end: number | undefined;
+}
+
+interface OpenSubagentSpan {
+  toolCallId: string;
+  agent: string;
+  mode: string;
+  start: number;
+}
+
+interface RunState {
+  startedAt: number;
+  prompt: string;
+  runs: number;
+  turns: number;
+  tools: Record<string, number>;
+  usage: UsageTotals;
+  status: WorkStatus;
+  waitingSpans: Interval[];
+  /** Waiting spans opened by interactive tools, keyed by tool call id. */
+  openToolWaits: Map<string, Interval>;
+  subagents: SubagentSpan[];
+  openSubagents: Map<string, OpenSubagentSpan>;
+}
+
+interface RunEndMessage {
+  role: string;
+  stopReason?: string;
+}
+
+/**
+ * Pure domain state machine that turns pi lifecycle events into finished
+ * {@link WorkRecord} entries. Holds no I/O; timestamps come from the
+ * injected {@link Clock} so behaviour is deterministic under test.
+ */
+export class WorkTracker {
+  private readonly clock: Clock;
+  private readonly interactiveTools: Set<string>;
+  private readonly subagentTool: string;
+  private state: RunState | undefined;
+
+  constructor(options: WorkTrackerOptions) {
+    this.clock = options.clock;
+    this.interactiveTools = new Set(options.interactiveTools);
+    this.subagentTool = options.subagentTool;
+  }
+
+  onRunStart(prompt: string): void {
+    if (!this.state) {
+      this.state = {
+        startedAt: this.clock.now(),
+        prompt,
+        runs: 1,
+        turns: 0,
+        tools: {},
+        usage: emptyUsage(),
+        status: "completed",
+        waitingSpans: [],
+        openToolWaits: new Map(),
+        subagents: [],
+        openSubagents: new Map(),
+      };
+      return;
+    }
+    this.state.runs++;
+  }
+
+  onTurnEnd(usage: Partial<UsageTotals> | undefined): void {
+    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;
+  }
+
+  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;
+
+    if (this.interactiveTools.has(toolName)) {
+      const span: Interval = { start: this.clock.now(), end: undefined };
+      this.state.waitingSpans.push(span);
+      this.state.openToolWaits.set(toolCallId, span);
+      return;
+    }
+
+    if (toolName === this.subagentTool) {
+      const agent = typeof args?.["agent"] === "string" ? (args["agent"] as string) : "unknown";
+      const mode = typeof args?.["mode"] === "string" ? (args["mode"] as string) : "task";
+      this.state.openSubagents.set(toolCallId, {
+        toolCallId,
+        agent,
+        mode,
+        start: this.clock.now(),
+      });
+    }
+  }
+
+  onToolEnd(toolCallId: string, result: unknown): void {
+    if (!this.state) return;
+
+    const openSubagent = this.state.openSubagents.get(toolCallId);
+    if (openSubagent) {
+      this.state.openSubagents.delete(toolCallId);
+      const taskId = extractTaskId(result);
+      this.state.subagents.push({
+        toolCallId: openSubagent.toolCallId,
+        agent: openSubagent.agent,
+        mode: openSubagent.mode,
+        ...(taskId !== undefined ? { taskId } : {}),
+        ms: this.clock.now() - openSubagent.start,
+      });
+      return;
+    }
+
+    const openWaitingSpan = this.state.openToolWaits.get(toolCallId);
+    if (openWaitingSpan) {
+      this.state.openToolWaits.delete(toolCallId);
+      openWaitingSpan.end = this.clock.now();
+    }
+  }
+
+  onUiPromptStart(_kind: string): void {
+    if (!this.state) return;
+    this.state.waitingSpans.push({ start: this.clock.now(), end: undefined });
+  }
+
+  onUiPromptEnd(_kind: string): void {
+    if (!this.state) return;
+    // Prompts are sequential; close the most recently opened span (LIFO).
+    for (let i = this.state.waitingSpans.length - 1; i >= 0; i--) {
+      const span = this.state.waitingSpans[i];
+      if (span && span.end === undefined) {
+        span.end = this.clock.now();
+        return;
+      }
+    }
+  }
+
+  onRunEnd(messages: RunEndMessage[]): void {
+    if (!this.state) return;
+    const lastAssistant = [...messages].reverse().find((message) => message.role === "assistant");
+    if (lastAssistant?.stopReason === "aborted") {
+      this.state.status = "aborted";
+    }
+  }
+
+  onSettled(): WorkRecordCore | undefined {
+    if (!this.state) return undefined;
+    const record = this.finalize(this.state.status);
+    this.state = undefined;
+    return record;
+  }
+
+  onShutdown(): WorkRecordCore | undefined {
+    if (!this.state) return undefined;
+    const record = this.finalize("interrupted");
+    this.state = undefined;
+    return record;
+  }
+
+  private finalize(status: WorkStatus): WorkRecordCore {
+    const state = this.state;
+    if (!state) {
+      throw new Error("finalize 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 waitingMs = unionMs(clampIntervals(closedSpans, state.startedAt, settledAt));
+    const workMs = wallMs - waitingMs;
+
+    return {
+      schema: WORK_RECORD_SCHEMA,
+      id: randomUUID(),
+      prompt: state.prompt,
+      startedAt: new Date(state.startedAt).toISOString(),
+      settledAt: new Date(settledAt).toISOString(),
+      wallMs,
+      waitingMs,
+      workMs,
+      runs: state.runs,
+      turns: state.turns,
+      tools: state.tools,
+      subagents: state.subagents,
+      usage: state.usage,
+      status,
+    };
+  }
+}
+
+function extractTaskId(result: unknown): string | undefined {
+  if (!result || typeof result !== "object") return undefined;
+  const details = (result as { details?: unknown }).details;
+  if (!details || typeof details !== "object") return undefined;
+  const gentleAgents = (details as { gentleAgents?: unknown }).gentleAgents;
+  if (!gentleAgents || typeof gentleAgents !== "object") return undefined;
+  const taskId = (gentleAgents as { taskId?: unknown }).taskId;
+  return typeof taskId === "string" ? taskId : undefined;
+}

package/src/extension.ts

@@ -0,0 +1,26 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { detectRole, loadConfig } from "./config.ts";
+import { WorkTracker } from "./domain/work-tracker.ts";
+import { LazyJsonlWorkLog } from "./adapters/lazy-jsonl-work-log.ts";
+import { createPiTracker } from "./adapters/pi-tracker.ts";
+
+export default function kankaku(pi: ExtensionAPI): void {
+  const config = loadConfig();
+  const role = detectRole();
+
+  const tracker = new WorkTracker({
+    clock: { now: () => Date.now() },
+    interactiveTools: config.interactiveTools,
+    subagentTool: config.subagentTool,
+  });
+
+  const log = new LazyJsonlWorkLog(config.dir);
+
+  createPiTracker(pi, {
+    tracker,
+    log,
+    role,
+    pid: process.pid,
+    parentPid: process.ppid,
+  });
+}

package/src/ports/clock.ts

@@ -0,0 +1,3 @@
+export interface Clock {
+  now(): number;
+}

package/src/ports/work-log.ts

@@ -0,0 +1,6 @@
+import type { WorkRecord } from "../domain/work-record.ts";
+
+export interface WorkLog {
+  append(record: WorkRecord): void;
+  readAll(): WorkRecord[];
+}