kankaku-claude 0.1.0

package/src/inflight-recovery.ts

@@ -0,0 +1,82 @@
+import { unlinkSync } from "node:fs";
+import { basename } from "node:path";
+import type { WorkRecord } from "kankaku/domain";
+import { listStateFiles } from "./paths.ts";
+import { readState } from "./session-state.ts";
+import { readEventLog } from "./event-log.ts";
+import { splitPrompts, replayPrompt } from "./replay.ts";
+import { buildClaudeRecord } from "./record.ts";
+import { readCost, deleteCost, type CostEnv } from "./cost-store.ts";
+
+export interface RecoverStaleSessionsInput {
+  claudeDir: string;
+  currentSessionId: string;
+  isAlive: (pid: number) => boolean;
+  now: number;
+  env: CostEnv;
+}
+
+/**
+ * Crash recovery: for every other session's state file whose pid is dead,
+ * replay its still-open prompt (if any) into an `interrupted` record, then
+ * delete that session's files (state, events, cost). A live session is left
+ * untouched.
+ *
+ * A non-positive `pid` counts as dead regardless of what `isAlive` reports
+ * (T7: the pre-fix `mergeCost` placeholder carried `pid: 0`, and the old
+ * `isAlive(0)` — `process.kill(0, 0)` signals the whole process GROUP —
+ * reported it alive forever). Such a placeholder also carries `cwd: ""`; an
+ * open prompt with no cwd to attribute it to is discarded, not replayed.
+ */
+export function recoverStaleSessions(input: RecoverStaleSessionsInput): WorkRecord[] {
+  const records: WorkRecord[] = [];
+
+  for (const stateFile of listStateFiles(input.claudeDir)) {
+    const sessionId = sessionIdFromStateFile(stateFile);
+    if (!sessionId || sessionId === input.currentSessionId) continue;
+
+    const state = readState(stateFile);
+    const eventsFile = stateFile.replace(/\.state\.json$/, ".events.jsonl");
+
+    if (!state) {
+      safeUnlink(stateFile);
+      safeUnlink(eventsFile);
+      continue;
+    }
+
+    const dead = state.pid <= 0 || !input.isAlive(state.pid);
+    if (!dead) continue;
+
+    if (state.promptOpen && state.cwd !== "") {
+      const events = readEventLog(eventsFile);
+      const prompts = splitPrompts(events);
+      const last = prompts[prompts.length - 1];
+      if (last && last.open) {
+        const core = replayPrompt(last, { settledAt: input.now });
+        if (core) {
+          const model = readCost(input.env, sessionId)?.model;
+          records.push(buildClaudeRecord(core, state, sessionId, model));
+        }
+      }
+    }
+
+    safeUnlink(stateFile);
+    safeUnlink(eventsFile);
+    deleteCost(input.env, sessionId);
+  }
+
+  return records;
+}
+
+function sessionIdFromStateFile(file: string): string | undefined {
+  const match = basename(file).match(/^(.*)\.state\.json$/);
+  return match?.[1];
+}
+
+function safeUnlink(file: string): void {
+  try {
+    unlinkSync(file);
+  } catch {
+    // already gone
+  }
+}

package/src/paths.ts

@@ -0,0 +1,50 @@
+import { readdirSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+
+export interface ResolvePathsInput {
+  env: NodeJS.ProcessEnv;
+  cwd: string;
+  sessionId: string;
+}
+
+export interface ResolvedPaths {
+  kankakuDir: string;
+  claudeDir: string;
+  eventsFile: string;
+  stateFile: string;
+}
+
+/**
+ * Same rule as kankaku's `resolveKankakuDir` (kankaku/hub): an absolute
+ * `KANKAKU_DIR` is used as-is, a relative one is joined against the session's
+ * cwd. Inlined rather than imported so the light hooks (one per tool call)
+ * never load the hub barrel for a two-line helper.
+ */
+export function resolveKankakuDir(dirOrRelative: string, cwd: string): string {
+  return isAbsolute(dirOrRelative) ? dirOrRelative : join(cwd, dirOrRelative);
+}
+
+/** `<KANKAKU_DIR or .kankaku>/claude/<sessionId>.{events.jsonl,state.json}`. */
+export function resolvePaths(input: ResolvePathsInput): ResolvedPaths {
+  const kankakuDir = resolveKankakuDir(input.env.KANKAKU_DIR ?? ".kankaku", input.cwd);
+  const claudeDir = join(kankakuDir, "claude");
+  return {
+    kankakuDir,
+    claudeDir,
+    eventsFile: join(claudeDir, `${input.sessionId}.events.jsonl`),
+    stateFile: join(claudeDir, `${input.sessionId}.state.json`),
+  };
+}
+
+/** Every `*.state.json` path in `claudeDir`, absolute. Empty array when the directory does not exist. */
+export function listStateFiles(claudeDir: string): string[] {
+  let entries: string[];
+  try {
+    entries = readdirSync(claudeDir);
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((name) => name.endsWith(".state.json"))
+    .map((name) => join(claudeDir, name));
+}

package/src/prompts.ts

@@ -0,0 +1,42 @@
+import type { Event } from "./events.ts";
+
+export interface PromptEvents {
+  events: Event[];
+  /** `false` once the prompt's terminal Stop has been seen; `true` while it is still in progress or was interrupted. */
+  open: boolean;
+}
+
+/**
+ * Groups a session's event stream into prompts: each group starts at a
+ * `UserPromptSubmit` and collects every following event up to (and
+ * including) the next `UserPromptSubmit`. A group is closed (`open: false`)
+ * only when its last event is a `Stop` — a Stop followed by more events (a
+ * Stop-hook-continued turn) leaves the group open until a later Stop
+ * actually terminates it, or forever if it never does (interrupted).
+ * Leading events before any `UserPromptSubmit` are ignored.
+ */
+export function splitPrompts(events: Event[]): PromptEvents[] {
+  const prompts: PromptEvents[] = [];
+  let current: Event[] | undefined;
+
+  for (const event of events) {
+    if (event.event === "UserPromptSubmit") {
+      if (current) {
+        prompts.push({ events: current, open: isOpen(current) });
+      }
+      current = [event];
+      continue;
+    }
+    if (!current) continue; // orphan event before any UserPromptSubmit
+    current.push(event);
+  }
+  if (current) {
+    prompts.push({ events: current, open: isOpen(current) });
+  }
+  return prompts;
+}
+
+function isOpen(events: Event[]): boolean {
+  const last = events[events.length - 1];
+  return last === undefined || last.event !== "Stop";
+}

package/src/record.ts

@@ -0,0 +1,28 @@
+import type { WorkRecord, WorkRecordCore } from "kankaku/domain";
+import type { SessionState } from "./session-state.ts";
+
+/**
+ * Attaches the orchestrator metadata a replayed {@link WorkRecordCore}
+ * needs to become a persistable {@link WorkRecord}. Phase 1: no
+ * `client`/`clientId` (hub sync is phase 2). `model` is the statusline
+ * model id (from `src/cost-store.ts#readCost`, since T7 no longer a field
+ * of `SessionState`) — passed in explicitly rather than read here, so the
+ * caller decides which cost snapshot's model applies.
+ */
+export function buildClaudeRecord(
+  core: WorkRecordCore,
+  state: SessionState,
+  sessionId: string,
+  model: string | undefined,
+): WorkRecord {
+  return {
+    ...core,
+    role: "orchestrator",
+    pid: state.pid,
+    parentPid: state.parentPid,
+    project: state.cwd,
+    sessionId,
+    mode: "claude-code",
+    ...(model ? { model: `anthropic/${model}` } : {}),
+  };
+}

package/src/replay.ts

@@ -0,0 +1,123 @@
+import { WorkTracker } from "kankaku/domain";
+import type { WorkRecordCore } from "kankaku/domain";
+import type { SubagentProfile } from "kankaku/domain";
+import type { Clock } from "kankaku/ports";
+import type { Event } from "./events.ts";
+
+/** Tool names whose span counts as waiting rather than working. */
+const INTERACTIVE_TOOLS = ["AskUserQuestion"];
+
+/**
+ * The plugin's own subagent profile: Claude Code's `Agent`/`Task` tool
+ * calls open a subagent span, read from `subagent_type`. No join key is
+ * offered (`SubagentStart`/`SubagentStop` are recorded but not linked — see
+ * odd/tasks/hook-tracking.md "Replay (pure)").
+ */
+const CLAUDE_CODE_SUBAGENT_PROFILE: SubagentProfile = {
+  id: "claude-code",
+  toolNames: ["Agent", "Task"],
+  childEnvMarkers: [],
+  joinKeyConfidence: "none",
+  readLaunchArgs: (args) => ({
+    agent: typeof args?.subagent_type === "string" ? args.subagent_type : "unknown",
+    mode: "task",
+  }),
+  readResult: () => ({}),
+};
+
+export { splitPrompts, type PromptEvents } from "./prompts.ts";
+import type { PromptEvents } from "./prompts.ts";
+
+export interface ReplayOptions {
+  /** Epoch ms to settle an open prompt at. Defaults to the last event's `ts`. */
+  settledAt?: number;
+  /** The prompt's cost delta (from the statusline), when known. */
+  cost?: number;
+}
+
+/**
+ * Feeds one prompt's events into a fresh {@link WorkTracker} and returns the
+ * resulting {@link WorkRecordCore}. Pure: all timestamps come from the
+ * events themselves (or `opts.settledAt`), never from the wall clock.
+ */
+export function replayPrompt(
+  prompt: PromptEvents,
+  opts: ReplayOptions = {},
+): WorkRecordCore | undefined {
+  if (prompt.events.length === 0) return undefined;
+
+  let current = prompt.events[0]!.ts;
+  const clock: Clock = { now: () => current };
+  const tracker = new WorkTracker({
+    clock,
+    interactiveTools: INTERACTIVE_TOOLS,
+    subagentProfiles: [CLAUDE_CODE_SUBAGENT_PROFILE],
+  });
+
+  const terminalStopIndex = prompt.open ? -1 : prompt.events.length - 1;
+  let permissionOpen = false;
+  let pendingAgentStart = false;
+  let settled: WorkRecordCore | undefined;
+
+  for (let i = 0; i < prompt.events.length; i++) {
+    const event = prompt.events[i]!;
+    current = event.ts;
+
+    if (permissionOpen) {
+      tracker.onUiPromptEnd("permission");
+      permissionOpen = false;
+    }
+    if (pendingAgentStart) {
+      tracker.onAgentStart();
+      pendingAgentStart = false;
+    }
+
+    switch (event.event) {
+      case "UserPromptSubmit":
+        tracker.onRunStart(event.prompt);
+        tracker.onAgentStart();
+        break;
+      case "PreToolUse":
+        tracker.onToolStart(event.toolUseId, event.toolName, event.toolInput);
+        break;
+      case "PostToolUse":
+        tracker.onToolEnd(event.toolUseId, undefined);
+        break;
+      case "PermissionRequest":
+        tracker.onUiPromptStart("permission");
+        permissionOpen = true;
+        break;
+      case "SubagentStart":
+      case "SubagentStop":
+        // Recorded on disk but not joined to any span — see the profile's
+        // doc comment: no documented link between agent_id and tool_use_id.
+        break;
+      case "Stop":
+        if (i === terminalStopIndex) {
+          if (typeof opts.cost === "number" && Number.isFinite(opts.cost)) {
+            tracker.onTurnEnd({ cost: opts.cost });
+          } else {
+            tracker.onTurnEnd(undefined);
+          }
+          tracker.onRunEnd([]);
+          settled = tracker.onSettled();
+        } else {
+          // A Stop-hook-continued turn: end this run's loop now so the next
+          // event's onAgentStart() opens a genuinely new run that gets
+          // folded back into the same record at the terminal settle,
+          // bumping `runs`.
+          tracker.onRunEnd([]);
+          pendingAgentStart = true;
+        }
+        break;
+      case "SessionStart":
+      case "SessionEnd":
+        break;
+    }
+  }
+
+  if (terminalStopIndex >= 0) return settled;
+
+  current = opts.settledAt ?? prompt.events[prompt.events.length - 1]!.ts;
+  return tracker.onShutdown();
+}

package/src/report.ts

@@ -0,0 +1,132 @@
+import { buildTasks } from "kankaku/domain";
+import type { TaskView, WorkRecord, WorkStatus } from "kankaku/domain";
+
+export interface FormatReportOptions {
+  /** Epoch ms "now" the window is measured back from. */
+  now: number;
+  /** How many trailing local days to include. Defaults to 7. */
+  days?: number;
+}
+
+const STATUS_WORD: Record<WorkStatus, string> = {
+  completed: "done",
+  interrupted: "interrupted",
+  aborted: "aborted",
+};
+
+const PROMPT_MAX_LENGTH = 60;
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+/**
+ * Renders a per-day, per-task report from raw {@link WorkRecord}s: builds
+ * {@link TaskView}s via `buildTasks`, keeps the ones started within the
+ * last `opts.days` local days (default 7), groups by local calendar day,
+ * and lists one line per task plus a per-day and a grand total.
+ */
+export function formatReport(records: WorkRecord[], opts: FormatReportOptions): string {
+  const days = opts.days ?? 7;
+  const cutoff = opts.now - days * MS_PER_DAY;
+
+  const tasks = buildTasks(records).filter((task) => new Date(task.startedAt).getTime() >= cutoff);
+
+  if (tasks.length === 0) {
+    return `No tasks recorded in the last ${days} days.\n`;
+  }
+
+  const byDay = new Map<string, TaskView[]>();
+  for (const task of tasks) {
+    const day = localDay(task.startedAt);
+    const group = byDay.get(day);
+    if (group) group.push(task);
+    else byDay.set(day, [task]);
+  }
+
+  const lines: string[] = [];
+  let grand = emptyTotals();
+
+  for (const day of [...byDay.keys()].sort()) {
+    const dayTasks = byDay.get(day)!.sort((a, b) => a.startedAt.localeCompare(b.startedAt));
+    lines.push(day);
+    let dayTotals = emptyTotals();
+    for (const task of dayTasks) {
+      lines.push(`  ${formatTaskLine(task)}`);
+      dayTotals = addTotals(dayTotals, totalsOf(task));
+    }
+    lines.push(`  ${formatTotalsLine(dayTasks.length, dayTotals)}`);
+    grand = addTotals(grand, dayTotals);
+  }
+
+  const grandTaskCount = tasks.length;
+  lines.push("");
+  lines.push(`Grand ${formatTotalsLine(grandTaskCount, grand)}`);
+
+  return lines.join("\n") + "\n";
+}
+
+interface Totals {
+  wallMs: number;
+  waitingMs: number;
+  workMs: number;
+  cost: number;
+}
+
+function emptyTotals(): Totals {
+  return { wallMs: 0, waitingMs: 0, workMs: 0, cost: 0 };
+}
+
+function totalsOf(task: TaskView): Totals {
+  return { wallMs: task.wallMs, waitingMs: task.waitingMs, workMs: task.workMs, cost: task.usage.cost };
+}
+
+function addTotals(a: Totals, b: Totals): Totals {
+  return {
+    wallMs: a.wallMs + b.wallMs,
+    waitingMs: a.waitingMs + b.waitingMs,
+    workMs: a.workMs + b.workMs,
+    cost: a.cost + b.cost,
+  };
+}
+
+function formatTaskLine(task: TaskView): string {
+  const time = localTime(task.startedAt);
+  const status = STATUS_WORD[task.status] ?? task.status;
+  const cost = task.usage.cost > 0 ? `$${task.usage.cost.toFixed(2)}` : "-";
+  const prompt = truncatePrompt(task.prompt);
+  return `${time}  ${status}  wall ${formatDuration(task.wallMs)}  wait ${formatDuration(task.waitingMs)}  work ${formatDuration(task.workMs)}  ${cost}  ${prompt}`;
+}
+
+function formatTotalsLine(taskCount: number, totals: Totals): string {
+  const label = taskCount === 1 ? "task" : "tasks";
+  return `total: ${taskCount} ${label}  wall ${formatDuration(totals.wallMs)}  wait ${formatDuration(totals.waitingMs)}  work ${formatDuration(totals.workMs)}  $${totals.cost.toFixed(2)}`;
+}
+
+/** `1h 02m`, `12m 05s`, or `8s` — matches the spec's examples exactly. */
+export function formatDuration(ms: number): string {
+  const totalSeconds = Math.max(0, Math.round(ms / 1000));
+  const hours = Math.floor(totalSeconds / 3600);
+  const minutes = Math.floor((totalSeconds % 3600) / 60);
+  const seconds = totalSeconds % 60;
+  if (hours > 0) return `${hours}h ${pad2(minutes)}m`;
+  if (minutes > 0) return `${minutes}m ${pad2(seconds)}s`;
+  return `${seconds}s`;
+}
+
+function pad2(n: number): string {
+  return String(n).padStart(2, "0");
+}
+
+function truncatePrompt(prompt: string): string {
+  const singleLine = prompt.replace(/\s+/g, " ").trim();
+  if (singleLine.length <= PROMPT_MAX_LENGTH) return singleLine;
+  return `${singleLine.slice(0, PROMPT_MAX_LENGTH - 1)}…`;
+}
+
+function localDay(iso: string): string {
+  const d = new Date(iso);
+  return `${d.getFullYear()}-${pad2(d.getMonth() + 1)}-${pad2(d.getDate())}`;
+}
+
+function localTime(iso: string): string {
+  const d = new Date(iso);
+  return `${pad2(d.getHours())}:${pad2(d.getMinutes())}`;
+}

package/src/session-state.ts

@@ -0,0 +1,71 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+export interface PromptOpenState {
+  id: string;
+  startedAt: number;
+  costAtStart: number | undefined;
+}
+
+/**
+ * `<claude/>/<session_id>.state.json` — small, rewritten atomically. Cost is
+ * NOT a field here (since T7, `odd/tasks/hook-tracking.md`): it lives under
+ * `~/.kankaku/claude/cost/` (`src/cost-store.ts`), never in a project's
+ * state file — only the hooks write this file.
+ */
+export interface SessionState {
+  pid: number;
+  parentPid: number;
+  cwd: string;
+  startedAt: number;
+  promptOpen: PromptOpenState | null;
+  permissionOpen: number | null;
+}
+
+/**
+ * A legacy state file written before T7 may still carry a `cost` field; an
+ * extra field is harmless (never required, never round-tripped by
+ * `writeState`), so it is not rejected here.
+ */
+function isSessionState(value: unknown): value is SessionState {
+  if (typeof value !== "object" || value === null) return false;
+  const o = value as Record<string, unknown>;
+  return (
+    typeof o.pid === "number" &&
+    typeof o.parentPid === "number" &&
+    typeof o.cwd === "string" &&
+    typeof o.startedAt === "number" &&
+    "promptOpen" in o &&
+    "permissionOpen" in o
+  );
+}
+
+/** `undefined` when the file is absent or its contents are malformed. */
+export function readState(file: string): SessionState | undefined {
+  let text: string;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch {
+    return undefined;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+  return isSessionState(parsed) ? parsed : undefined;
+}
+
+/** Atomic tmp+rename write, creating parent directories as needed. */
+export function writeState(file: string, state: SessionState): void {
+  mkdirSync(dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmp, JSON.stringify(state));
+  renameSync(tmp, file);
+}
+
+/** Read-modify-write: `fn` receives the current state (`undefined` if absent) and returns the next one. */
+export function updateState(file: string, fn: (state: SessionState | undefined) => SessionState): void {
+  writeState(file, fn(readState(file)));
+}

package/src/statusline-core.ts

@@ -0,0 +1,89 @@
+import { resolvePaths } from "./paths.ts";
+import type { readState, PromptOpenState } from "./session-state.ts";
+import type { writeCost } from "./cost-store.ts";
+
+export interface StatuslineDeps {
+  env: NodeJS.ProcessEnv;
+  /** Epoch ms; used to stamp a written cost and to compute the open prompt's elapsed clock. */
+  now: () => number;
+  readState: typeof readState;
+  writeCost: typeof writeCost;
+}
+
+/**
+ * Renders the Claude Code statusline line. Never throws: any parsing or
+ * I/O failure falls back to the bare `"kankaku"` string.
+ *
+ * Side effect: when `input.cost.total_cost_usd` is a finite number, writes
+ * it (and the model id, when present) to `~/.kankaku/claude/cost/<session_id>.json`
+ * via `deps.writeCost` — NEVER under the project (T7,
+ * `odd/tasks/hook-tracking.md`: the statusline command is wired globally in
+ * `~/.claude/settings.json`, so it runs in every session on the machine).
+ * The project's own state file (`<KANKAKU_DIR>/claude/<session_id>.state.json`)
+ * is only ever READ here, for the open-prompt clock, and is never created:
+ * a missing state file renders as `idle` rather than creating anything.
+ */
+export function renderStatusline(input: unknown, deps: StatuslineDeps): string {
+  try {
+    if (!isPlainObject(input)) return "kankaku";
+
+    const sessionId = readStringField(input.session_id);
+    const workspace = isPlainObject(input.workspace) ? input.workspace : undefined;
+    const cwd = readStringField(workspace?.current_dir) ?? readStringField(input.cwd);
+    if (!sessionId || !cwd) return "kankaku";
+
+    const cost = isPlainObject(input.cost) ? input.cost : undefined;
+    const totalUsd = readFiniteNumberField(cost?.total_cost_usd);
+    const model = isPlainObject(input.model) ? input.model : undefined;
+    const modelId = readStringField(model?.id);
+
+    if (totalUsd !== undefined) {
+      deps.writeCost(deps.env, sessionId, {
+        totalUsd,
+        updatedAt: deps.now(),
+        ...(modelId ? { model: modelId } : {}),
+      });
+    }
+
+    const paths = resolvePaths({ env: deps.env, cwd, sessionId });
+    const state = deps.readState(paths.stateFile);
+    const clock = formatClock(state?.promptOpen ?? null, deps.now());
+
+    return totalUsd !== undefined ? `kankaku ${clock} · $${totalUsd.toFixed(2)}` : `kankaku ${clock}`;
+  } catch {
+    return "kankaku";
+  }
+}
+
+function formatClock(promptOpen: PromptOpenState | null, now: number): string {
+  if (!promptOpen) return "idle";
+  return formatElapsed(Math.max(0, now - promptOpen.startedAt));
+}
+
+/** `m:ss` under an hour, `h:mm:ss` from an hour onward. */
+function formatElapsed(ms: number): string {
+  const totalSeconds = Math.floor(ms / 1000);
+  const hours = Math.floor(totalSeconds / 3600);
+  const minutes = Math.floor((totalSeconds % 3600) / 60);
+  const seconds = totalSeconds % 60;
+  if (hours > 0) {
+    return `${hours}:${pad2(minutes)}:${pad2(seconds)}`;
+  }
+  return `${minutes}:${pad2(seconds)}`;
+}
+
+function pad2(n: number): string {
+  return String(n).padStart(2, "0");
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function readStringField(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+function readFiniteNumberField(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}

package/src/statusline.ts

@@ -0,0 +1,36 @@
+import { renderStatusline } from "./statusline-core.ts";
+import { readState } from "./session-state.ts";
+import { writeCost } from "./cost-store.ts";
+
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk as Buffer);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+async function main(): Promise<void> {
+  let input: unknown;
+  try {
+    const text = await readStdin();
+    input = JSON.parse(text);
+  } catch {
+    input = undefined;
+  }
+  const line = renderStatusline(input, {
+    env: process.env,
+    now: () => Date.now(),
+    readState,
+    writeCost,
+  });
+  process.stdout.write(`${line}\n`);
+}
+
+main()
+  .catch(() => {
+    process.stdout.write("kankaku\n");
+  })
+  .finally(() => {
+    process.exit(0);
+  });