kankaku 0.1.0 → 0.4.6

package/src/adapters/pi-tracker.ts

@@ -1,41 +1,52 @@
 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 { WorkRecord, WorkRecordCore, WorkRole } from "../domain/work-record.ts";
+import type { WorkTracker } from "../domain/work-tracker.ts";
+import type { InflightStore } from "../ports/inflight-store.ts";
 import type { WorkLog } from "../ports/work-log.ts";
-import { formatReport, formatSessions, formatTasks, localDay, summarize } from "./report.ts";
+import { createSessionClient } from "./session-client.ts";
+import { createStatusBar } from "./status-bar.ts";
+import { notifyError, registerKankakuCommand } from "./kankaku-command.ts";
+
+export type { KankakuReportData } from "./kankaku-command.ts";
 
 export interface PiTrackerDeps {
   tracker: WorkTracker;
   log: WorkLog;
+  /** Crash-recovery checkpoint store; see the "Crash recovery" README section. */
+  inflight: InflightStore;
   role: WorkRole;
   pid: number;
   parentPid: number;
   /** Status line refresh interval in ms. Defaults to 1000. */
   statusIntervalMs?: number;
+  /** Whether a pid is still alive. Defaults to signal-probing with `process.kill(pid, 0)`. */
+  isAlive?: (pid: number) => boolean;
+  /** Default billing client for this project, from `KANKAKU_CLIENT` (config.ts). See `domain/client-label.ts`. */
+  envClient?: string;
+  /**
+   * Lazily reads the project's default billing client from
+   * `<kankaku dir>/config.json`. Injected from `extension.ts` so this
+   * adapter stays free of filesystem code.
+   */
+  resolveProjectClient?: () => string | undefined;
+  /**
+   * Write an export file (name, content) under the kankaku dir and return
+   * its absolute path. Injected from `extension.ts` to keep this adapter
+   * free of filesystem code. `/kankaku export` notifies an error when this
+   * is not configured.
+   */
+  writeExportFile?: (name: string, content: string) => string;
 }
 
-const STATUS_KEY = "kankaku";
-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");
+/** Default `isAlive`: probe with signal 0 — no signal is sent, only existence/permission is checked. */
+function defaultIsAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    // EPERM means the process exists but we lack permission to signal it — still alive.
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
 }
 
 /** Wraps a handler so it never throws out of the pi event loop. */
@@ -54,36 +65,40 @@ function guarded<E>(fn: (event: E, ctx: ExtensionContext) => void): (event: E, c
  * records to a {@link WorkLog} and exposing the `/kankaku` report command.
  */
 export function createPiTracker(pi: ExtensionAPI, deps: PiTrackerDeps): void {
-  const { tracker, log, role, pid, parentPid } = deps;
-  const statusIntervalMs = deps.statusIntervalMs ?? 1000;
+  const { tracker, log, inflight, role, pid, parentPid } = deps;
+  const isAlive = deps.isAlive ?? defaultIsAlive;
 
-  let runStartedAt: number | undefined;
-  let statusTimer: NodeJS.Timeout | undefined;
+  const sessionClient = createSessionClient({
+    role,
+    envClient: deps.envClient,
+    resolveProjectClient: deps.resolveProjectClient,
+  });
 
-  function stopStatus(ctx: ExtensionContext): void {
-    if (statusTimer) {
-      clearInterval(statusTimer);
-      statusTimer = undefined;
-    }
-    if (ctx.hasUI) {
-      ctx.ui.setStatus(STATUS_KEY, undefined);
-    }
-    runStartedAt = undefined;
-  }
+  const statusBar = createStatusBar({
+    intervalMs: deps.statusIntervalMs,
+    resolveRunClient: () => sessionClient.runClient(),
+    resolveIdleClient: () => sessionClient.idleClient(),
+  });
+
+  const kankakuCommand = registerKankakuCommand(pi, {
+    log,
+    sessionClient,
+    refreshIdleStatus: (ctx) => statusBar.showIdle(ctx),
+    writeExportFile: deps.writeExportFile,
+  });
 
-  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?.();
+  /** `log.append` plus cache invalidation, so every append this process makes keeps the completion cache correct. */
+  function appendRecord(record: WorkRecord): void {
+    log.append(record);
+    kankakuCommand.invalidateClientNames();
   }
 
-  function buildRecord(core: NonNullable<ReturnType<WorkTracker["onSettled"]>>, ctx: ExtensionContext): WorkRecord {
+  function buildRecord(core: WorkRecordCore, ctx: ExtensionContext): WorkRecord {
     const model = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined;
+    // Subagent children never carry their own client: they inherit the
+    // orchestrator's label at task level (see task-view.ts).
+    const client = sessionClient.runClient();
+    const sessionName = pi.getSessionName();
     return {
       ...core,
       role,
@@ -94,14 +109,32 @@ export function createPiTracker(pi: ExtensionAPI, deps: PiTrackerDeps): void {
       sessionFile: ctx.sessionManager.getSessionFile(),
       mode: ctx.mode,
       ...(model !== undefined ? { model } : {}),
+      ...(client !== undefined ? { client } : {}),
+      ...(sessionName !== undefined ? { sessionName } : {}),
     };
   }
 
+  /**
+   * Save an in-flight checkpoint of the run's current state, so a hard
+   * crash before the next one (or the final settle) still leaves a
+   * recoverable `interrupted` record. A no-op while idle.
+   */
+  function checkpoint(ctx: ExtensionContext): void {
+    const core = tracker.peek("interrupted");
+    if (core) {
+      inflight.save(buildRecord(core, ctx));
+    }
+  }
+
   pi.on(
     "before_agent_start",
     guarded((event, ctx) => {
       tracker.onRunStart(event.prompt);
-      if (runStartedAt === undefined) startStatus(ctx);
+      statusBar.start(ctx);
+      // Checkpoint right away so a crash on the very first turn (before any
+      // turn_end/tool_execution_end) still leaves a recoverable in-flight
+      // record; see the "Crash recovery" README section.
+      checkpoint(ctx);
     }),
   );
 
@@ -114,9 +147,10 @@ export function createPiTracker(pi: ExtensionAPI, deps: PiTrackerDeps): void {
 
   pi.on(
     "turn_end",
-    guarded((event) => {
+    guarded((event, ctx) => {
       const message = event.message;
       const usage = message && "usage" in message ? message.usage : undefined;
+      const cost = usage && typeof usage.cost === "object" && usage.cost !== null ? usage.cost.total : undefined;
       tracker.onTurnEnd(
         usage
           ? {
@@ -124,10 +158,11 @@ export function createPiTracker(pi: ExtensionAPI, deps: PiTrackerDeps): void {
               output: usage.output,
               cacheRead: usage.cacheRead,
               cacheWrite: usage.cacheWrite,
-              cost: usage.cost.total,
+              cost,
             }
           : undefined,
       );
+      checkpoint(ctx);
     }),
   );
 
@@ -140,8 +175,9 @@ export function createPiTracker(pi: ExtensionAPI, deps: PiTrackerDeps): void {
 
   pi.on(
     "tool_execution_end",
-    guarded((event) => {
+    guarded((event, ctx) => {
       tracker.onToolEnd(event.toolCallId, event.result);
+      checkpoint(ctx);
     }),
   );
 
@@ -163,10 +199,17 @@ export function createPiTracker(pi: ExtensionAPI, deps: PiTrackerDeps): void {
     "agent_settled",
     guarded((_event, ctx) => {
       const core = tracker.onSettled();
-      if (core) {
-        log.append(buildRecord(core, ctx));
+      try {
+        if (core) {
+          appendRecord(buildRecord(core, ctx));
+        }
+      } finally {
+        // Always clean up, even when appendRecord above threw: an unpersisted
+        // checkpoint must not linger, and the status timer must not leak.
+        inflight.clear();
+        statusBar.stop(ctx);
+        sessionClient.endRun();
       }
-      stopStatus(ctx);
     }),
   );
 
@@ -174,70 +217,31 @@ export function createPiTracker(pi: ExtensionAPI, deps: PiTrackerDeps): void {
     "session_shutdown",
     guarded((_event, ctx) => {
       const core = tracker.onShutdown();
-      if (core) {
-        log.append(buildRecord(core, ctx));
+      try {
+        if (core) {
+          appendRecord(buildRecord(core, ctx));
+        }
+      } finally {
+        inflight.clear();
+        statusBar.stop(ctx);
+        sessionClient.endRun();
       }
-      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;
-        }
+  pi.on(
+    "session_start",
+    guarded((_event, ctx) => {
+      sessionClient.restore(ctx);
+      statusBar.showIdle(ctx);
 
-        const summary = summarize(records, { all });
-        showReport(ctx, {
-          title: all ? "summary (all days)" : "summary (today)",
-          lines: formatReport(summary).split(" | "),
-        });
-      } catch (error) {
-        notifyError(ctx, error);
+      const recovered = inflight.recoverStale(isAlive);
+      for (const record of recovered) {
+        appendRecord(record);
       }
-    },
-  });
+      if (recovered.length > 0 && ctx.hasUI) {
+        ctx.ui.notify(`kankaku: recovered ${recovered.length} interrupted record(s)`, "warning");
+      }
+    }),
+  );
 }

package/src/adapters/project-config.ts

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

package/src/adapters/report.ts

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

package/src/adapters/session-client.ts

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