kankaku 0.4.5 → 0.5.0

package/src/adapters/process-identity.ts

@@ -0,0 +1,162 @@
+import { detectRole, readRoleOverride, stripRoleOverride } from "../config.ts";
+import type { RoleOverride } from "../config.ts";
+import { resolveOrchestratorRef } from "../domain/ancestry-match.ts";
+import type { OrchestratorRef } from "../domain/work-record.ts";
+import { GENTLE_PI_PROFILE, builtinChildMarkers, configuredChildMarkers, matchesAnyMarker, resolveChildProfile } from "../domain/subagent-profile.ts";
+import type { SubagentProfile } from "../domain/subagent-profile.ts";
+import type { ProcessRegistry, RegistryEntry } from "../ports/process-registry.ts";
+import { resolveSubagentStartup } from "./subagent-startup.ts";
+import type { AncestrySnapshot } from "./ancestry.ts";
+
+/** `resolveProcessIdentity`'s default `subagentProfiles` when a caller does not pass its own active profile set: exactly gentle-pi's own marker, matching this module's behaviour before SUBAGENT-REQ-001/002/003 existed — so a caller that has not opted into the wider profile set (e.g. an existing test) keeps behaving byte-for-byte the same. */
+const DEFAULT_SUBAGENT_PROFILES: readonly SubagentProfile[] = [GENTLE_PI_PROFILE];
+
+/**
+ * Everything about THIS OS process's identity that `role` (and everything
+ * derived from it — `orchestratorRef`, F1's write-routing target) depends
+ * on. Computed once by {@link resolveProcessIdentity}; see
+ * `process-identity-memo.ts` for why a caller must never simply call this
+ * again on a same-process factory re-invocation (G1).
+ */
+export interface ProcessIdentity {
+  role: "orchestrator" | "subagent";
+  /** `KANKAKU_ROLE`, as read BEFORE this call strips it from `deps.env` — never re-derivable afterwards. */
+  roleOverride: RoleOverride | undefined;
+  /** Whether `GENTLE_PI_AGENTS_CHILD=1` was present (never stripped, so re-reading `env` later would still agree — kept here anyway so every process-level fact lives in one place). */
+  childMarkerPresent: boolean;
+  /** See `config.ts#RoleDetection.overrideIgnoredInteractive`. */
+  overrideIgnoredInteractive: true | undefined;
+  /** C2: see `config.ts#RoleDetection.configuredMarkerIgnoredInteractive`. */
+  configuredMarkerIgnoredInteractive: true | undefined;
+  /** Whether a live, identity-verified tracked ancestor was found via the machine-wide registry (F2/F3's `hasTrackedAncestor`). */
+  hasTrackedAncestor: boolean;
+  /** The nearest verified tracked ancestor's own registry entry, if any. */
+  ancestorEntry: RegistryEntry | undefined;
+  /** F4: the real top-level orchestrator's ref, resolved through a possible subagent-of-subagent chain. `undefined` for an `orchestrator`-role process. */
+  orchestratorRef: OrchestratorRef | undefined;
+  /** F5: this process's own OS start-time identity, derived without a subprocess spawn. */
+  ownProcessStartId: number;
+  /** Live start-identity lookup from the same ancestry snapshot `resolveSubagentStartup` took (or a fail-safe always-unknown function when it never took one — F5). */
+  liveStartId: (pid: number) => number | undefined;
+  /**
+   * SUBAGENT-REQ-005/017: the {@link SubagentProfile} `id` whose child-env
+   * marker(s) confirmed this process's `role: "subagent"` classification,
+   * when exactly one profile's marker matched. `undefined` when no known
+   * marker matched (role, if `subagent`, then came from ancestry alone) or
+   * when 2+ matched at once (never guessed). Always `undefined` for an
+   * `orchestrator`-role process.
+   */
+  profile: string | undefined;
+}
+
+export interface ResolveProcessIdentityDeps {
+  /** This process's own env. Mutated in place: the override is stripped after being read (R1, layer 2). */
+  env: NodeJS.ProcessEnv;
+  registry: ProcessRegistry;
+  /** This process's own OS parent pid (`process.ppid`). */
+  ppid: number;
+  /** `Date.now`, injected. */
+  now: () => number;
+  /** `process.uptime`, injected. */
+  uptimeSeconds: () => number;
+  /** A cheap, synchronous interactivity proxy (`process.stdout.isTTY`) — see `config.ts#detectRole`'s doc comment. */
+  isInteractiveGuess: boolean;
+  /** Injectable for tests; forwarded to `resolveSubagentStartup`. */
+  snapshotAncestry?: () => AncestrySnapshot;
+  /**
+   * SUBAGENT-REQ-001/002/003/005: the full active {@link SubagentProfile}
+   * set (`config.ts#loadConfig`'s `subagentProfiles`) whose child-env
+   * markers confirm a subagent, generalised beyond gentle-pi's own. Defaults
+   * to gentle-pi alone — this module's exact pre-6b behaviour — so a caller
+   * that has not opted into the wider set (an existing test, or any
+   * embedder that has not been updated) sees no change at all.
+   */
+  subagentProfiles?: readonly SubagentProfile[];
+}
+
+/**
+ * Compute this OS process's role/ancestry identity exactly once: reads
+ * `KANKAKU_ROLE` and the confirmed-child marker, walks the machine-wide
+ * registry/ancestor chain only when it could find something (F5), decides
+ * `role` (R1's precedence), strips the override from `deps.env` so no
+ * child this process spawns ever inherits it (R1, layer 2), and resolves
+ * the verified `orchestratorRef` (F4) a subagent routes its writes to
+ * (F1's write-routing target, alongside this process's own resolved dir —
+ * see `extension.ts`).
+ *
+ * Mirrors what used to be inlined directly in `extension.ts` (and still is,
+ * independently, in `scripts/e2e-cross-worktree-real-processes.ts`'s
+ * `runStartup`, which exercises this exact sequence against real OS
+ * processes) — pulled out into its own function so
+ * `process-identity-memo.ts` (G1) can freeze its result across a
+ * same-process factory re-invocation (`/new`/`/resume`/`/fork`/`/reload`)
+ * without `extension.ts` duplicating this sequence, and so this exact
+ * sequence has one place to be tested directly.
+ */
+export function resolveProcessIdentity(deps: ResolveProcessIdentityDeps): ProcessIdentity {
+  const startup = resolveSubagentStartup({
+    registry: deps.registry,
+    ppid: deps.ppid,
+    now: deps.now,
+    uptimeSeconds: deps.uptimeSeconds,
+    ...(deps.snapshotAncestry !== undefined ? { snapshotAncestry: deps.snapshotAncestry } : {}),
+  });
+  const hasTrackedAncestor = startup.ancestorEntry !== undefined;
+
+  // SUBAGENT-REQ-001/002/003/005: the full active profile set's markers,
+  // generalising the single hardcoded GENTLE_PI_AGENTS_CHILD check this
+  // module used before — see DEFAULT_SUBAGENT_PROFILES for why an omitted
+  // `deps.subagentProfiles` is a complete no-op. C2: split into two tiers —
+  // built-in markers always win; the user-configured one never demotes an
+  // interactive session (see `config.ts#detectRole`'s doc comment).
+  const profiles = deps.subagentProfiles ?? DEFAULT_SUBAGENT_PROFILES;
+  const builtinMarkers = builtinChildMarkers(profiles);
+  const userConfiguredMarkers = configuredChildMarkers(profiles);
+
+  // R1 (BLOCKER): read KANKAKU_ROLE, and whether A confirmed BUILT-IN child
+  // marker (from any recognised profile) is present, exactly once here —
+  // then strip the override from this process's own env so a child this
+  // process spawns never inherits it. `childMarkerPresent` deliberately
+  // reflects the built-in tier only — it backs the doctor's "the confirmed
+  // child marker takes precedence" message (`kankaku-command.ts`), which is
+  // only true for this tier (C2).
+  const childMarkerPresent = matchesAnyMarker(deps.env, builtinMarkers);
+  const roleOverride = readRoleOverride(deps.env);
+  // `hasTrackedAncestor` is irrelevant to `role` itself (only to the
+  // separately-deferred `roleConfidence`, resolved later by the caller),
+  // so `false` is passed here purely to obtain `role`/`overrideIgnoredInteractive` cheaply.
+  const detection = detectRole(deps.env, false, deps.isInteractiveGuess, builtinMarkers, userConfiguredMarkers);
+  const { role } = detection;
+  const overrideIgnoredInteractive = detection.overrideIgnoredInteractive === true ? true : undefined;
+  const configuredMarkerIgnoredInteractive = detection.configuredMarkerIgnoredInteractive === true ? true : undefined;
+  stripRoleOverride(deps.env);
+
+  // SUBAGENT-REQ-005/017 + C2 item 3: WHICH profile's marker confirmed this
+  // process, if exactly one did (never guessed — see resolveChildProfile) —
+  // but only ever attributed when this process actually ended up
+  // classified `subagent`. A configured marker present but ignored for
+  // interactivity (role stays `orchestrator`) must never carry a
+  // `profile`: an orchestrator record with `profile: "configured"` would
+  // be a self-contradictory pair no doctor/report reader could make sense
+  // of.
+  const profile = role === "subagent" ? resolveChildProfile(profiles, deps.env).profile?.id : undefined;
+
+  // F4: resolves through a subagent-of-subagent chain to the real top-level
+  // orchestrator (never a middle hop), carrying that orchestrator's `dir`
+  // for F1's write routing.
+  const orchestratorRef = role === "subagent" ? resolveOrchestratorRef(startup.ancestorEntry) : undefined;
+
+  return {
+    role,
+    roleOverride,
+    childMarkerPresent,
+    overrideIgnoredInteractive,
+    configuredMarkerIgnoredInteractive,
+    hasTrackedAncestor,
+    ancestorEntry: startup.ancestorEntry,
+    orchestratorRef,
+    ownProcessStartId: startup.ownProcessStartId,
+    liveStartId: startup.liveStartId,
+    profile,
+  };
+}

package/src/adapters/project-config.ts

@@ -1,5 +1,6 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import type { WorkTargetCandidate } from "../domain/work-target.ts";
 import { resolveKankakuDir } from "./kankaku-dir.ts";
 
 const CONFIG_FILE_NAME = "config.json";
@@ -42,3 +43,74 @@ export class LazyProjectClientSource {
     return readProjectClient(resolveKankakuDir(this.dirOrRelative, this.fallbackCwd()));
   }
 }
+
+/**
+ * Read `clientId`/`projectId` from `<dir>/config.json`, the lowest-precedence
+ * source in `domain/work-target.ts#resolveWorkTarget`. Tolerates the same
+ * failure modes as {@link readProjectClient}. `undefined` when `clientId`
+ * is absent or not a string (a `projectId` without a `clientId` is not a
+ * valid candidate); a non-string `projectId` is dropped, keeping `clientId`.
+ */
+export function readProjectTargetIds(dir: string): WorkTargetCandidate | 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 record = parsed as Record<string, unknown>;
+    const clientId = record["clientId"];
+    if (typeof clientId !== "string") return undefined;
+    const projectId = record["projectId"];
+    return typeof projectId === "string" ? { clientId, projectId } : { clientId };
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Merge `clientId`/`projectId` into `<dir>/config.json`, preserving every
+ * other existing key (including the legacy `client` label). Writes
+ * atomically (tmp + rename), mirroring `file-inflight-store.ts`. A missing
+ * or malformed existing file is treated as `{}` rather than failing.
+ */
+export function writeProjectTargetIds(dir: string, ids: WorkTargetCandidate): void {
+  const filePath = join(dir, CONFIG_FILE_NAME);
+  let existing: Record<string, unknown> = {};
+  if (existsSync(filePath)) {
+    try {
+      const parsed: unknown = JSON.parse(readFileSync(filePath, "utf8"));
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        existing = parsed as Record<string, unknown>;
+      }
+    } catch {
+      existing = {};
+    }
+  }
+
+  const merged = { ...existing, clientId: ids.clientId, ...(ids.projectId !== undefined ? { projectId: ids.projectId } : {}) };
+
+  mkdirSync(dir, { recursive: true });
+  const tmp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmp, JSON.stringify(merged, null, 2));
+  renameSync(tmp, filePath);
+}
+
+/** Reads target ids from a kankaku dir resolved lazily against `fallbackCwd()` at call time. */
+export class LazyProjectTargetSource {
+  private readonly dirOrRelative: string;
+  private readonly fallbackCwd: () => string;
+
+  constructor(dirOrRelative: string, fallbackCwd: () => string = () => process.cwd()) {
+    this.dirOrRelative = dirOrRelative;
+    this.fallbackCwd = fallbackCwd;
+  }
+
+  read(): WorkTargetCandidate | undefined {
+    return readProjectTargetIds(resolveKankakuDir(this.dirOrRelative, this.fallbackCwd()));
+  }
+
+  write(ids: WorkTargetCandidate): void {
+    writeProjectTargetIds(resolveKankakuDir(this.dirOrRelative, this.fallbackCwd()), ids);
+  }
+}

package/src/adapters/report.ts

@@ -1,4 +1,4 @@
-import { buildTasks } from "../domain/task-view.ts";
+import { buildTasks, uncertainRecords } 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";
@@ -42,10 +42,16 @@ function emptyTotals(): RoleTotals {
   return { workMs: 0, waitingMs: 0, wallMs: 0, count: 0, cost: 0, segments: {} };
 }
 
-/** Add per-tag milliseconds from `segments` (missing on older records) into `into`. */
-function addSegments(into: Record<string, number>, segments: Record<string, number> | undefined): void {
+/**
+ * Add per-tag milliseconds from `segments` (missing on older records) into
+ * `into`, a `Map` rather than a plain object so a tag from a hand-edited
+ * worklog line named `__proto__` or `constructor` accumulates as a normal
+ * entry instead of silently reading (and arithmetically corrupting) an
+ * inherited `Object.prototype` value.
+ */
+function addSegments(into: Map<string, number>, segments: Record<string, number> | undefined): void {
   for (const [tag, ms] of Object.entries(segments ?? {})) {
-    into[tag] = (into[tag] ?? 0) + ms;
+    into.set(tag, (into.get(tag) ?? 0) + ms);
   }
 }
 
@@ -63,6 +69,10 @@ export function summarize(records: WorkRecord[], options: SummarizeOptions): Sum
     subagent: emptyTotals(),
     tasks: { count: 0, wallMs: 0, workMs: 0, cost: 0, segments: {} },
   };
+  // Accumulated in Maps (see `addSegments`) and only converted to the
+  // returned plain objects at the very end, via `Object.fromEntries`.
+  const segmentsByRole: Record<WorkRole, Map<string, number>> = { orchestrator: new Map(), subagent: new Map() };
+  const taskSegments = new Map<string, number>();
 
   for (const record of records) {
     if (targetDay !== undefined && localDay(record.startedAt) !== targetDay) continue;
@@ -72,7 +82,7 @@ export function summarize(records: WorkRecord[], options: SummarizeOptions): Sum
     totals.wallMs += record.wallMs;
     totals.count += 1;
     totals.cost += finiteOrZero(record.usage.cost);
-    addSegments(totals.segments, record.segments);
+    addSegments(segmentsByRole[record.role], record.segments);
   }
 
   const tasks = buildTasks(records).filter((task) => targetDay === undefined || localDay(task.startedAt) === targetDay);
@@ -81,12 +91,27 @@ 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);
+    addSegments(taskSegments, task.segments);
   }
 
+  summary.orchestrator.segments = Object.fromEntries(segmentsByRole.orchestrator);
+  summary.subagent.segments = Object.fromEntries(segmentsByRole.subagent);
+  summary.tasks.segments = Object.fromEntries(taskSegments);
+
   return summary;
 }
 
+/**
+ * Count of `uncertain` records (ADR 0022) within the same day scope
+ * `summarize` uses, so the `/kankaku` report can surface a one-line hint
+ * when some records are silently excluded from the task count
+ * (SUBAGENT-REQ-017): an undercount must never be silent.
+ */
+export function countUncertain(records: WorkRecord[], options: SummarizeOptions): number {
+  const targetDay = options.all ? undefined : (options.day ?? localDay(new Date().toISOString()));
+  return uncertainRecords(records).filter((record) => targetDay === undefined || localDay(record.startedAt) === targetDay).length;
+}
+
 function formatMinutes(ms: number): string {
   const totalSeconds = Math.round(ms / 1000);
   const minutes = Math.floor(totalSeconds / 60);
@@ -131,12 +156,20 @@ export function formatReport(summary: Summary): string {
   return lines.join(" | ");
 }
 
-/** Render one line per task: time, client (when present), union-based wall/work, cost, non-zero segment tags, 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;
+      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}` : "";
@@ -179,6 +212,54 @@ export function summarizeByClient(tasks: TaskView[]): Map<string, ClientTotals>
   return totals;
 }
 
+export interface ProjectTotals {
+  /** Display name: the project's `projectName`, or `"(no project)"` for the ungrouped bucket. */
+  name: string;
+  wallMs: number;
+  waitingMs: number;
+  workMs: number;
+  /** Estimated cost in USD, summed across this project's tasks. */
+  cost: number;
+  count: number;
+}
+
+/** Key (and display name) under which tasks without a resolved project are grouped. */
+const NO_PROJECT = "(no project)";
+
+/**
+ * Aggregate tasks by hub project (see `domain/work-target.ts`), keyed by
+ * `projectId` (so two projects that happen to share a display name are
+ * never merged) with the name denormalised alongside for display. Tasks
+ * without a `projectId` are grouped under `"(no project)"`.
+ */
+export function summarizeByProject(tasks: TaskView[]): Map<string, ProjectTotals> {
+  const totals = new Map<string, ProjectTotals>();
+  for (const task of tasks) {
+    const key = task.projectId ?? NO_PROJECT;
+    const name = task.projectId !== undefined ? (task.projectName ?? task.projectId) : NO_PROJECT;
+    const entry = totals.get(key) ?? { name, 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 project, sorted alphabetically by display name, with work/waiting/wall time, cost, and task count. */
+export function formatProjects(totals: Map<string, ProjectTotals>): string {
+  if (totals.size === 0) return "no projects";
+  return Array.from(totals.values())
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .map(
+      (t) =>
+        `${t.name}  work ${formatMinutes(t.workMs)}  waiting ${formatMinutes(t.waitingMs)}  wall ${formatMinutes(t.wallMs)}  ${formatCost(t.cost)}  tasks ${t.count}`,
+    )
+    .join("\n");
+}
+
 /** 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";

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 };
+}

package/src/adapters/session-dir.ts

@@ -0,0 +1,28 @@
+/**
+ * `SessionManager#usesDefaultSessionDir()`/`#getSessionDir()` are real
+ * methods on pi's session manager (mirrors what pi's own
+ * `formatResumeCommand` does to decide whether to print `--session-dir`),
+ * but `usesDefaultSessionDir` is not part of the `ReadonlySessionManager`
+ * type `ctx.sessionManager` is typed as — so this is a guarded duck-typed
+ * call, not a typed one: an older pi version (or any future shape change)
+ * that lacks the method degrades to "no sessionDir," never a crash.
+ * Returns the session dir only when it is genuinely non-default, exactly
+ * the condition under which pi itself would print `--session-dir`. Shared
+ * by `pi-tracker.ts` (record metadata) and `kankaku-command.ts` (the
+ * `/kankaku doctor` display) — kept as its own module so neither adapter
+ * has to import the other.
+ */
+export function readNonDefaultSessionDir(sessionManager: unknown): string | undefined {
+  const candidate = sessionManager as { usesDefaultSessionDir?: () => boolean; getSessionDir?: () => string };
+  if (typeof candidate.usesDefaultSessionDir !== "function" || typeof candidate.getSessionDir !== "function") return undefined;
+  try {
+    if (candidate.usesDefaultSessionDir()) return undefined;
+    const dir = candidate.getSessionDir();
+    // An unpersisted session (e.g. `--no-session`) can report
+    // usesDefaultSessionDir() === false with an empty getSessionDir() — not
+    // a real custom directory, so there is nothing meaningful to carry.
+    return dir ? dir : undefined;
+  } catch {
+    return undefined;
+  }
+}