kankaku 0.4.6 → 0.5.1

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);
@@ -187,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-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;
+  }
+}