kankaku-pi 1.0.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

@@ -0,0 +1,116 @@
+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";
+
+/**
+ * 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()));
+  }
+}
+
+/**
+ * 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-data.ts

@@ -0,0 +1,13 @@
+/**
+ * Pi-free home for {@link KankakuReportData}, the shape every `/kankaku`
+ * report view and the panel's report screen produce. Extracted out of
+ * `kankaku-command.ts` (which still re-exports it) so `report-views.ts` can
+ * be published through `kankaku-pi/hub` without pulling in anything that
+ * touches `@earendil-works/*` — see AGENTS.md "Code conventions".
+ */
+
+/** Durable report rendered inside the chat transcript; never sent to the LLM. */
+export interface KankakuReportData {
+  title: string;
+  lines: string[];
+}

package/src/adapters/report-views.ts

@@ -0,0 +1,98 @@
+/**
+ * The five `/kankaku` report views (summary/tasks/sessions/clients/
+ * projects), each as one pure `WorkRecord[] -> KankakuReportData` builder.
+ * Extracted from `kankaku-command.ts`'s subcommand handlers (see
+ * odd/tasks/kankaku-panel.md P3) so the `/kankaku` subcommands and the
+ * panel's report screen (`panel/screens/report.ts`) always compute the
+ * exact same lines — neither ever re-implements the other's logic.
+ */
+import { buildSessions, buildTasks } from "../domain/task-view.ts";
+import { exportRows, toCsv, toJson } from "../domain/export.ts";
+import type { WorkRecord } from "../domain/work-record.ts";
+import type { KankakuReportData } from "./report-data.ts";
+import { countUncertain, formatClients, formatProjects, formatReport, formatSessions, formatTasks, localDay, summarize, summarizeByClient, summarizeByProject } from "./report.ts";
+
+/** Shared by every view except `buildTasksView`: `all` includes every day, otherwise only today's local day. */
+export interface ReportViewOptions {
+  all: boolean;
+}
+
+/** `buildTasksView`'s own options: `all` scopes to every session instead of local-day range (tasks are never day-filtered — see `kankaku-command.ts`'s original `tasks` handler). */
+export interface TasksViewOptions {
+  all: boolean;
+  sessionId: string | undefined;
+}
+
+/** The plain-text summary view (`/kankaku` with no view token): role/task totals, plus a one-line hint when uncertain records were excluded (SUBAGENT-REQ-017). */
+export function buildSummaryView(records: WorkRecord[], options: ReportViewOptions): KankakuReportData {
+  const { all } = options;
+  const summary = summarize(records, { all });
+  const lines = formatReport(summary).split(" | ");
+  const uncertainCount = countUncertain(records, { all });
+  if (uncertainCount > 0) {
+    lines.push(`kankaku: ${uncertainCount} uncertain record(s) excluded from tasks — run /kankaku doctor`);
+  }
+  return { title: all ? "summary (all days)" : "summary (today)", lines };
+}
+
+/** `/kankaku clients [all]`: per-client totals. */
+export function buildClientsView(records: WorkRecord[], options: ReportViewOptions): KankakuReportData {
+  const { all } = options;
+  const today = localDay(new Date().toISOString());
+  const tasks = buildTasks(records).filter((task) => all || localDay(task.startedAt) === today);
+  return { title: all ? "clients (all days)" : "clients (today)", lines: formatClients(summarizeByClient(tasks)).split("\n") };
+}
+
+/** `/kankaku projects [all]`: per-project totals. */
+export function buildProjectsView(records: WorkRecord[], options: ReportViewOptions): KankakuReportData {
+  const { all } = options;
+  const today = localDay(new Date().toISOString());
+  const tasks = buildTasks(records).filter((task) => all || localDay(task.startedAt) === today);
+  return { title: all ? "projects (all days)" : "projects (today)", lines: formatProjects(summarizeByProject(tasks)).split("\n") };
+}
+
+/** `/kankaku sessions [all]`: per-session totals. */
+export function buildSessionsView(records: WorkRecord[], options: ReportViewOptions): KankakuReportData {
+  const { all } = options;
+  const today = localDay(new Date().toISOString());
+  const tasks = buildTasks(records).filter((task) => all || localDay(task.startedAt) === today);
+  return { title: all ? "sessions (all days)" : "sessions (today)", lines: formatSessions(buildSessions(tasks)).split("\n") };
+}
+
+/**
+ * `/kankaku tasks [all]`: one line per task. Unlike every other view, tasks
+ * are never restricted by local day — `all` (or a missing `sessionId`)
+ * instead scopes from "this session" to "every session".
+ */
+export function buildTasksView(records: WorkRecord[], options: TasksViewOptions): KankakuReportData {
+  const { all, sessionId } = options;
+  const scoped = all || !sessionId;
+  const tasks = buildTasks(records).filter((task) => scoped || task.sessionId === sessionId);
+  return { title: scoped ? "tasks (every session)" : "tasks (this session)", lines: formatTasks(tasks).split("\n") };
+}
+
+/** {@link buildExportContent}'s options: `format` picks csv/json, `all` includes every day instead of just today's local day (mirrors every other view except `buildTasksView`). */
+export interface ExportContentOptions {
+  format: "csv" | "json";
+  all: boolean;
+}
+
+/**
+ * `/kankaku export [csv|json] [all]`'s file content: the flat export rows
+ * for today's (or every) task, rendered as csv or json, with the file name
+ * `/kankaku export` and the panel's export screen (`panel/screens/
+ * export.ts`) both use. Extracted from `kankaku-command.ts`'s
+ * `handleExportCommand` (see odd/tasks/kankaku-panel.md P4) so the
+ * subcommand and the panel never drift. `rowCount` is exposed only for the
+ * subcommand's "wrote N row(s) to <path>" confirmation line — the panel's
+ * own confirmation is simpler ("wrote <path>").
+ */
+export function buildExportContent(records: WorkRecord[], options: ExportContentOptions): { name: string; content: string; rowCount: number } {
+  const { format, all } = options;
+  const today = localDay(new Date().toISOString());
+  const tasks = buildTasks(records).filter((task) => all || localDay(task.startedAt) === today);
+  const rows = exportRows(tasks);
+  const content = format === "json" ? toJson(rows) : toCsv(rows);
+  const name = `tasks-${all ? "all" : today}.${format}`;
+  return { name, content, rowCount: rows.length };
+}