kankaku-pi 1.0.0

package/dist/ports/work-sink.d.ts

@@ -0,0 +1,39 @@
+import type { TaskView } from "../domain/task-view.ts";
+/** Which client a successfully pushed task ended up linked to, for the sync summary's `unassigned` grouping. See `domain/hub-entry.ts#resolveTaskAssignment`. */
+export interface PushAssignment {
+    /** `true` when the task was routed to the catalog's unassigned ("Sin determinar") client. */
+    unassigned: boolean;
+    /** The task's historical free-text/denormalised client label, only meaningful when `unassigned` is `true`. */
+    legacyLabel?: string;
+}
+/** Outcome of pushing one task's `task_entries` row (and, if enabled, its `work_records` children). */
+export type PushOutcome = ({
+    kind: "created";
+} & PushAssignment) | ({
+    kind: "updated";
+} & PushAssignment)
+/** A non-retryable rejection (e.g. a real validation error) — recorded and skipped, not retried automatically. */
+ | {
+    kind: "failed";
+    reason: string;
+}
+/** A network/timeout/5xx/auth failure. The caller must stop processing further tasks and not advance past this point. */
+ | {
+    kind: "error";
+    reason: string;
+};
+export interface PushTaskResult {
+    taskId: string;
+    outcome: PushOutcome;
+}
+/**
+ * Uploads consolidated task rows to the hub. `push` is given tasks already
+ * sorted chronologically by the caller and returns one result per task
+ * attempted, in the same order — stopping (returning fewer results than
+ * tasks given) at the first `"error"` outcome, since that signals a
+ * systemic failure (network/timeout/5xx/auth) rather than a per-task one.
+ * Never throws.
+ */
+export interface WorkSink {
+    push(tasks: TaskView[]): Promise<PushTaskResult[]>;
+}

package/dist/ports/work-sink.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "kankaku-pi",
+  "version": "1.0.0",
+  "description": "pi extension that records agent work time per prompt, excluding waits for the user, with subagent linkage and task/session views",
+  "license": "MIT",
+  "author": "soyunninja",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/soyunninja/kankaku.git",
+    "directory": "packages/pi"
+  },
+  "homepage": "https://kankaku.io",
+  "bugs": {
+    "url": "https://github.com/soyunninja/kankaku/issues"
+  },
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "time-tracking",
+    "agents"
+  ],
+  "files": [
+    "src/",
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    "./domain": {
+      "types": "./dist/domain/index.d.ts",
+      "import": "./dist/domain/index.js"
+    },
+    "./ports": {
+      "types": "./dist/ports/index.d.ts",
+      "import": "./dist/ports/index.js"
+    },
+    "./hub": {
+      "types": "./dist/hub/index.d.ts",
+      "import": "./dist/hub/index.js"
+    },
+    "./package.json": "./package.json",
+    "./src/*": "./src/*"
+  },
+  "pi": {
+    "extensions": [
+      "./src/extension.ts"
+    ]
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "node --test tests/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "check": "npm run build && npm run typecheck && npm test",
+    "e2e:hub": "node scripts/e2e-hub.ts",
+    "e2e:cross-worktree": "node scripts/e2e-cross-worktree-real-processes.ts",
+    "prepublishOnly": "npm run check"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.85.1",
+    "@earendil-works/pi-tui": "^0.85.1",
+    "@types/node": "^24.13.4",
+    "typescript": "^5.7.0"
+  }
+}

package/src/adapters/agent-info.ts

@@ -0,0 +1,86 @@
+/**
+ * Resolve `agent_version`/`plugin_version` for the hub's "Agent and
+ * measurement quality" fields (`domain/hub-entry.ts`). Neither pi's
+ * `ExtensionAPI` nor `ExtensionContext` exposes a version today (checked
+ * against `@earendil-works/pi-coding-agent`'s type definitions), so pi's
+ * own version is instead read from its installed package's `package.json`
+ * — the same file Node's module resolution already points at. Both
+ * resolvers run once, at extension load time (never a hot path), and
+ * degrade to `undefined` on any failure: this is a best-effort label, and
+ * a wrong guess is worse than an absent one.
+ */
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+export interface AgentInfoDeps {
+  /** Reads a file's contents as text. Defaults to `fs.readFileSync(path, "utf8")`. Injectable for tests. */
+  readFile?: (path: string) => string;
+  /** Resolves a bare module specifier to a `file://` URL, like `import.meta.resolve`. Injectable for tests. */
+  resolveModule?: (specifier: string) => string;
+}
+
+function defaultReadFile(path: string): string {
+  return readFileSync(path, "utf8");
+}
+
+function readVersionField(path: string, readFile: (path: string) => string): string | undefined {
+  try {
+    const parsed = JSON.parse(readFile(path)) as { version?: unknown };
+    return typeof parsed.version === "string" ? parsed.version : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** kankaku's own version, from the `package.json` at `packageRoot` (the directory containing `src/`). */
+export function resolvePluginVersion(packageRoot: string, deps: AgentInfoDeps = {}): string | undefined {
+  const readFile = deps.readFile ?? defaultReadFile;
+  return readVersionField(join(packageRoot, "package.json"), readFile);
+}
+
+const MAX_UPWARD_HOPS = 6;
+
+/**
+ * pi's own version, resolved from the installed
+ * `@earendil-works/pi-coding-agent` package: resolve its entry module, then
+ * walk upward from that file looking for the nearest `package.json` whose
+ * own `name` field actually matches the package (handling a nested
+ * `dist/...` entry point), so a coincidental unrelated `package.json`
+ * higher up a directory tree is never trusted.
+ */
+export function resolveAgentVersion(deps: AgentInfoDeps = {}): string | undefined {
+  const readFile = deps.readFile ?? defaultReadFile;
+  const resolveModule = deps.resolveModule ?? ((specifier: string) => import.meta.resolve(specifier));
+
+  let entryUrl: string;
+  try {
+    entryUrl = resolveModule("@earendil-works/pi-coding-agent");
+  } catch {
+    return undefined;
+  }
+
+  let dir: string;
+  try {
+    dir = dirname(fileURLToPath(entryUrl));
+  } catch {
+    return undefined;
+  }
+
+  for (let hop = 0; hop < MAX_UPWARD_HOPS; hop++) {
+    try {
+      const parsed = JSON.parse(readFile(join(dir, "package.json"))) as { name?: unknown; version?: unknown };
+      if (parsed.name === "@earendil-works/pi-coding-agent" && typeof parsed.version === "string") {
+        return parsed.version;
+      }
+    } catch {
+      // Not here (or unreadable/malformed) — keep walking up.
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  return undefined;
+}

package/src/adapters/ancestry.ts

@@ -0,0 +1,260 @@
+import { execFileSync } from "node:child_process";
+import { readFileSync, readdirSync } from "node:fs";
+import { platform } from "node:os";
+
+/**
+ * One OS ancestor-chain snapshot: `pid -> ppid` for every process visible to
+ * this user at the moment it was taken, plus each pid's approximate OS
+ * start-time identity (`startIdByPid`, epoch-ms estimate). The identity map
+ * is used to prove a pid still refers to the same process instance a
+ * registry entry was written for (see `domain/ancestry-match.ts`); it is
+ * empty for a pid whose start time could not be determined (also always
+ * empty on Windows), never a reason to fail the ppid-map part of the
+ * snapshot.
+ */
+export interface AncestrySnapshot {
+  ppidByPid: Map<number, number>;
+  startIdByPid: Map<number, number>;
+}
+
+/** One raw `pid -> ppid` and `pid -> startId` read, before either mechanism is chosen. */
+export interface ProcSnapshot {
+  ppidByPid: Map<number, number>;
+  startIdByPid: Map<number, number>;
+}
+
+/** Parse `ps -eo pid,ppid[,...]` output (header line plus one `<pid> <ppid> ...` row per line) into a `pid -> ppid` map. Extra trailing columns (e.g. `etimes`) are ignored here. */
+export function parsePsOutput(output: string): Map<number, number> {
+  const map = new Map<number, number>();
+  const lines = output.split("\n").slice(1); // drop the header line
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const parts = trimmed.split(/\s+/);
+    const pid = Number(parts[0]);
+    const ppid = Number(parts[1]);
+    if (Number.isFinite(pid) && Number.isFinite(ppid)) map.set(pid, ppid);
+  }
+  return map;
+}
+
+/**
+ * `ps`'s portable elapsed-time column is `etime` (`[[dd-]hh:]mm:ss`), not
+ * the GNU-only `etimes` (plain seconds): BSD `ps` — macOS included — has no
+ * `etimes` keyword at all and errors out on it, which would silently break
+ * ancestor-chain detection everywhere on that platform (the `ps` fallback
+ * throws, degrading straight to an empty snapshot) — a real regression
+ * caught by testing this against a real `ps` before trusting it. `etime`,
+ * by contrast, is supported by both BSD and GNU `ps`.
+ */
+const ETIME_PATTERN = /^(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+)$/;
+
+/** Parse one `ps` `etime` value (`[[dd-]hh:]mm:ss`) into whole seconds, or `undefined` if it does not match the expected shape. */
+export function parseEtimeSeconds(etime: string): number | undefined {
+  const match = ETIME_PATTERN.exec(etime.trim());
+  if (!match) return undefined;
+  const days = match[1] !== undefined ? Number(match[1]) : 0;
+  const hours = match[2] !== undefined ? Number(match[2]) : 0;
+  const minutes = Number(match[3]);
+  const seconds = Number(match[4]);
+  if (![days, hours, minutes, seconds].every(Number.isFinite)) return undefined;
+  return days * 86400 + hours * 3600 + minutes * 60 + seconds;
+}
+
+/**
+ * Parse the `etime` (elapsed time since start, `[[dd-]hh:]mm:ss`) column
+ * out of `ps -eo pid,ppid,etime` output into an approximate start-epoch-ms
+ * estimate per pid: `nowMs - etimeSeconds * 1000`. `etime` truncates to
+ * whole seconds, so this is accurate to within about a second either way —
+ * well within `domain/ancestry-match.ts`'s tolerance.
+ */
+export function parsePsEtimes(output: string, nowMs: number): Map<number, number> {
+  const map = new Map<number, number>();
+  const lines = output.split("\n").slice(1);
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const parts = trimmed.split(/\s+/);
+    const pid = Number(parts[0]);
+    const etimeSeconds = parts[2] !== undefined ? parseEtimeSeconds(parts[2]) : undefined;
+    if (Number.isFinite(pid) && etimeSeconds !== undefined) map.set(pid, nowMs - etimeSeconds * 1000);
+  }
+  return map;
+}
+
+const PPID_LINE = /^PPid:\s*(\d+)/m;
+
+/** Extract the `PPid:` value from one `/proc/<pid>/status` file's contents, or `undefined` when the line is missing/malformed. Kept as a small tested utility; the live snapshot path below reads `/proc/<pid>/stat` instead, since that file carries both ppid and start time in a single read. */
+export function parseProcStatus(status: string): number | undefined {
+  const match = PPID_LINE.exec(status);
+  if (!match) return undefined;
+  const ppid = Number(match[1]);
+  return Number.isFinite(ppid) ? ppid : undefined;
+}
+
+/**
+ * Parse one `/proc/<pid>/stat` line: `pid (comm) state ppid ... starttime ...`.
+ * `comm` (the process name) is parenthesized and may itself contain spaces
+ * or parens, so every field is located relative to the *last* `)` on the
+ * line, never by naive whitespace-splitting from the start. `ppid` is field
+ * 4 overall (index 1 after the comm) and `starttime` is field 22 overall
+ * (index 19) — the number of clock ticks since boot at which this process
+ * started, per `proc(5)`.
+ */
+export function parseProcStat(stat: string): { ppid: number; starttimeTicks: number } | undefined {
+  const closeParen = stat.lastIndexOf(")");
+  if (closeParen === -1) return undefined;
+  const rest = stat.slice(closeParen + 1).trim();
+  if (!rest) return undefined;
+  const fields = rest.split(/\s+/);
+  const ppid = Number(fields[1]);
+  const starttimeTicks = Number(fields[19]);
+  if (!Number.isFinite(ppid) || !Number.isFinite(starttimeTicks)) return undefined;
+  return { ppid, starttimeTicks };
+}
+
+/** Parse the first number (system uptime in seconds) out of `/proc/uptime`'s contents. */
+export function parseProcUptimeSeconds(content: string): number | undefined {
+  const first = content.trim().split(/\s+/)[0];
+  const value = first !== undefined ? Number(first) : NaN;
+  return Number.isFinite(value) ? value : undefined;
+}
+
+/**
+ * The near-universal Linux `USER_HZ` (clock ticks per second used by
+ * `/proc/<pid>/stat`'s `starttime` field), assumed rather than queried
+ * (Node has no `sysconf` binding). A wrong assumption never produces a
+ * false *match*: the same (possibly wrong) constant is used both when an
+ * entry is first written and whenever it is later re-verified, and
+ * `starttimeTicks` is fixed for a process's lifetime, so two readings of
+ * the *same* process instance still agree closely regardless of the true
+ * `USER_HZ` — only the (unused) absolute-epoch interpretation would be
+ * off. See `domain/ancestry-match.ts`.
+ */
+const ASSUMED_USER_HZ = 100;
+
+/** One `ps -eo pid,ppid,etimes` snapshot — a single subprocess spawn regardless of how many ancestor hops are later walked (SUBAGENT-REQ-011), carrying start-time identity alongside the ppid map. */
+function readSnapshotViaPs(): ProcSnapshot {
+  const output = execFileSync("ps", ["-eo", "pid,ppid,etime"], { encoding: "utf8", timeout: 2000 });
+  const nowMs = Date.now();
+  return { ppidByPid: parsePsOutput(output), startIdByPid: parsePsEtimes(output, nowMs) };
+}
+
+/** `/proc/<pid>/stat` reads — no subprocess spawn at all, cheaper than the `ps` snapshot, Linux-only. Carries start-time identity (`/proc/uptime` + `starttime` ticks) alongside the ppid map, at no extra spawn cost. */
+function readSnapshotViaProc(): ProcSnapshot {
+  const ppidByPid = new Map<number, number>();
+  const starttimeTicksByPid = new Map<number, number>();
+
+  for (const name of readdirSync("/proc")) {
+    const pid = Number(name);
+    if (!Number.isFinite(pid)) continue;
+    try {
+      const parsed = parseProcStat(readFileSync(`/proc/${name}/stat`, "utf8"));
+      if (parsed) {
+        ppidByPid.set(pid, parsed.ppid);
+        starttimeTicksByPid.set(pid, parsed.starttimeTicks);
+      }
+    } catch {
+      // The process exited between listing and reading, or is unreadable; skip it.
+    }
+  }
+
+  const startIdByPid = new Map<number, number>();
+  if (starttimeTicksByPid.size > 0) {
+    try {
+      const uptimeSec = parseProcUptimeSeconds(readFileSync("/proc/uptime", "utf8"));
+      if (uptimeSec !== undefined) {
+        const bootEpochMs = Date.now() - uptimeSec * 1000;
+        for (const [pid, ticks] of starttimeTicksByPid) {
+          startIdByPid.set(pid, bootEpochMs + (ticks / ASSUMED_USER_HZ) * 1000);
+        }
+      }
+    } catch {
+      // /proc/uptime unavailable: the ppid map above is still useful on its own; start ids just stay empty.
+    }
+  }
+
+  return { ppidByPid, startIdByPid };
+}
+
+export interface SnapshotAncestryDeps {
+  /** Defaults to `os.platform()`. Windows (`"win32"`) always yields an empty snapshot — no supported mechanism, never a spawn attempt (SUBAGENT-REQ-012). */
+  platform?: NodeJS.Platform;
+  /** Injectable for tests, so no test ever reads the real `/proc`. */
+  readProc?: () => ProcSnapshot;
+  /** Injectable for tests, so no test ever spawns a real `ps`. */
+  readPs?: () => ProcSnapshot;
+}
+
+/**
+ * Take one ancestor-chain snapshot: `/proc` first (cheapest, Linux), falling
+ * back to `ps -eo pid,ppid,etimes` (macOS, or a Linux without `/proc`
+ * mounted). Windows — and any environment where both mechanisms fail —
+ * degrades to an empty snapshot rather than throwing or blocking
+ * (SUBAGENT-REQ-012): callers see "no tracked ancestor found," never a
+ * crash. `startIdByPid` may legitimately be sparser than `ppidByPid` (a
+ * pid whose start time could not be read); callers must treat a missing
+ * start id as "unprovable," never as a match.
+ */
+export function snapshotAncestry(deps: SnapshotAncestryDeps = {}): AncestrySnapshot {
+  const osPlatform = deps.platform ?? platform();
+  if (osPlatform === "win32") return { ppidByPid: new Map(), startIdByPid: new Map() };
+
+  const readProc = deps.readProc ?? readSnapshotViaProc;
+  const readPs = deps.readPs ?? readSnapshotViaPs;
+
+  try {
+    return readProc();
+  } catch {
+    // /proc unavailable (macOS, or a Linux without it mounted); fall through to ps.
+  }
+  try {
+    return readPs();
+  } catch {
+    return { ppidByPid: new Map(), startIdByPid: new Map() };
+  }
+}
+
+/**
+ * This process's own approximate OS start-time identity, derived with no
+ * subprocess spawn and no `/proc` read at all: `nowMs - uptimeSeconds *
+ * 1000`, both sampled once at factory time (`process.uptime()` is measured
+ * from this process's own actual start, so it is unaffected by system
+ * sleep/wake — unlike a wall-clock-only estimate, it keeps counting only
+ * while this process itself has been running). Kept separate from
+ * `startIdByPid` (which comes from an ancestry snapshot that costs a `ps`
+ * spawn or `/proc` scan) so the common case — no other kankaku process on
+ * the machine, nothing to compare against — never pays for one just to
+ * record this process's own identity (see `adapters/subagent-startup.ts`).
+ * Expected to agree with the `ps`/`/proc`-derived value for the same
+ * process, within `domain/ancestry-match.ts#START_ID_TOLERANCE_MS`, since
+ * both are estimates of the same real start time from different sources.
+ */
+export function ownStartIdFromUptime(nowMs: number, uptimeSeconds: number): number {
+  return nowMs - uptimeSeconds * 1000;
+}
+
+const DEFAULT_MAX_HOPS = 20;
+
+/**
+ * Walk from `startPid` (typically this process's own `parentPid`) upward
+ * via `ppidByPid`, collecting ancestor pids in order, nearest first.
+ * Stops at `maxHops`, at pid 0/1 (the OS/init root), or when the chain
+ * leaves the snapshot (a pid with no known ppid) — a non-tracked
+ * intermediate hop (e.g. a thin shell wrapper) is walked past, not stopped
+ * at, since it simply has no entry of its own in the caller's registry
+ * lookup (SUBAGENT-REQ-011).
+ */
+export function walkAncestry(startPid: number, ppidByPid: Map<number, number>, maxHops: number = DEFAULT_MAX_HOPS): number[] {
+  const ancestors: number[] = [];
+  const seen = new Set<number>();
+  let current: number | undefined = startPid;
+
+  for (let hop = 0; hop < maxHops && current !== undefined && current > 1 && !seen.has(current); hop++) {
+    ancestors.push(current);
+    seen.add(current);
+    current = ppidByPid.get(current);
+  }
+
+  return ancestors;
+}

package/src/adapters/cached-catalog.ts

@@ -0,0 +1,147 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import type { Client, HubTask, Project } from "../domain/work-target.ts";
+import type { Clock } from "../ports/clock.ts";
+import type { Catalog, CatalogSnapshot } from "../ports/catalog.ts";
+import { OWNER_DIR_MODE, OWNER_FILE_MODE } from "./file-modes.ts";
+
+/** Six hours in milliseconds — clients and projects change rarely. */
+const DEFAULT_TTL_MS = 6 * 60 * 60 * 1000;
+
+function isClientArray(value: unknown): value is Client[] {
+  return Array.isArray(value) && value.every((item) => item && typeof item === "object" && typeof (item as Client).id === "string");
+}
+
+function isProjectArray(value: unknown): value is Project[] {
+  return Array.isArray(value) && value.every((item) => item && typeof item === "object" && typeof (item as Project).id === "string");
+}
+
+function isHubTaskArray(value: unknown): value is HubTask[] {
+  return Array.isArray(value) && value.every((item) => item && typeof item === "object" && typeof (item as HubTask).id === "string");
+}
+
+function isCatalogSnapshot(value: unknown): value is CatalogSnapshot {
+  if (!value || typeof value !== "object") return false;
+  const record = value as Record<string, unknown>;
+  return (
+    typeof record["fetchedAt"] === "number" &&
+    typeof record["url"] === "string" &&
+    isClientArray(record["clients"]) &&
+    isProjectArray(record["projects"]) &&
+    (record["tasks"] === undefined || isHubTaskArray(record["tasks"]))
+  );
+}
+
+export interface CachedCatalogDeps {
+  /** Absolute path to the cache file, e.g. `~/.kankaku/catalog.json`. */
+  filePath: string;
+  /** The configured hub URL; a cache written for a different URL is ignored. */
+  url: string;
+  clock: Clock;
+  /** Cache TTL in ms. Defaults to 6 hours. */
+  ttlMs?: number;
+  /**
+   * Fetch a fresh `{ clients, projects, tasks }` triple, e.g.
+   * `createPocketBaseCatalogFetcher(...)`. `tasks` is optional here (unlike
+   * on the real PocketBase fetcher) so a test double that only cares about
+   * clients/projects keeps compiling unchanged.
+   */
+  fetchCatalog: (signal?: AbortSignal) => Promise<{ clients: Client[]; projects: Project[]; tasks?: HubTask[] }>;
+}
+
+/**
+ * Disk-backed {@link Catalog}: `read()` is a synchronous, cheap read of the
+ * last known snapshot (memoised after the first disk read so repeated
+ * calls in one process never re-stat/re-parse); `refresh()` fetches, caches
+ * to disk atomically (tmp + rename, mirroring `file-inflight-store.ts`),
+ * and never throws — a failed refresh resolves `undefined` and leaves the
+ * previous snapshot (if any) untouched.
+ */
+export class CachedCatalog implements Catalog {
+  private readonly deps: CachedCatalogDeps;
+  private memo: CatalogSnapshot | undefined;
+  private memoized = false;
+
+  constructor(deps: CachedCatalogDeps) {
+    this.deps = deps;
+  }
+
+  read(): CatalogSnapshot | undefined {
+    if (!this.memoized) {
+      this.memo = this.readDisk();
+      this.memoized = true;
+    }
+    return this.memo;
+  }
+
+  isStale(): boolean {
+    const snapshot = this.read();
+    if (!snapshot) return true;
+    const ttl = this.deps.ttlMs ?? DEFAULT_TTL_MS;
+    return this.deps.clock.now() - snapshot.fetchedAt > ttl;
+  }
+
+  async refresh(signal?: AbortSignal): Promise<CatalogSnapshot | undefined> {
+    try {
+      const { clients, projects, tasks } = await this.deps.fetchCatalog(signal);
+      const snapshot: CatalogSnapshot = {
+        fetchedAt: this.deps.clock.now(),
+        url: this.deps.url,
+        clients,
+        projects,
+        ...(tasks !== undefined ? { tasks } : {}),
+      };
+      this.writeDisk(snapshot);
+      this.memo = snapshot;
+      this.memoized = true;
+      return snapshot;
+    } catch {
+      return undefined;
+    }
+  }
+
+  private readDisk(): CatalogSnapshot | undefined {
+    try {
+      if (!existsSync(this.deps.filePath)) return undefined;
+      const parsed: unknown = JSON.parse(readFileSync(this.deps.filePath, "utf8"));
+      if (!isCatalogSnapshot(parsed)) return undefined;
+      if (parsed.url !== this.deps.url) return undefined;
+      return parsed;
+    } catch {
+      return undefined;
+    }
+  }
+
+  private writeDisk(snapshot: CatalogSnapshot): void {
+    try {
+      // This cache lives under `~/.kankaku` (machine-wide, not a project's
+      // own KANKAKU_DIR) — but `~/.kankaku` itself is never mode-tightened
+      // here (R2): when pi runs with cwd === $HOME, a project's own default
+      // KANKAKU_DIR (`.kankaku`, relative) resolves to this exact same
+      // path, and a project's kankaku dir must never be tightened
+      // (AGENTS.md). Only what this package exclusively owns is touched:
+      // an EXISTING directory is never chmod'd — `mkdirSync`'s own `mode`
+      // option only ever applies to a directory this call actually
+      // creates, never one that already existed (Node skips the mkdir
+      // syscall for an existing path segment entirely, mode and all), so
+      // passing `mode` here is safe even though this path may be a
+      // project's own dir (G3). When this call IS the first writer (no
+      // `~/.kankaku` yet at all, e.g. a machine with the hub configured but
+      // no project ever run from $HOME), it is created owner-only
+      // (`OWNER_DIR_MODE`, 0700) rather than left at the umask default. The
+      // cache file itself is always written fresh via tmp+rename with
+      // OWNER_FILE_MODE below, which already guarantees 0600 on every
+      // write regardless of whatever mode an older file at this path (or
+      // an older kankaku build) left behind — a rename replaces the whole
+      // inode, so a stale looser mode can never survive a write.
+      mkdirSync(dirname(this.deps.filePath), { recursive: true, mode: OWNER_DIR_MODE });
+      const tmp = `${this.deps.filePath}.${process.pid}.${Date.now()}.tmp`;
+      // Owner-only: this file names every client/project the machine's user has touched.
+      writeFileSync(tmp, JSON.stringify(snapshot), { mode: OWNER_FILE_MODE });
+      renameSync(tmp, this.deps.filePath);
+    } catch {
+      // Best-effort cache write: a failure here must not fail the refresh
+      // itself, since the in-memory snapshot is still usable this process.
+    }
+  }
+}

package/src/adapters/export-writer.ts

@@ -0,0 +1,33 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { resolveKankakuDir } from "./kankaku-dir.ts";
+
+const EXPORT_SUBDIR = "export";
+
+/**
+ * Write `content` to `<dir>/export/<name>` (creating the `export`
+ * subdirectory as needed, overwriting any existing file with the same
+ * name) and return the absolute path it was written to.
+ */
+export function writeExport(dir: string, name: string, content: string): string {
+  const exportDir = join(dir, EXPORT_SUBDIR);
+  mkdirSync(exportDir, { recursive: true });
+  const filePath = resolve(join(exportDir, name));
+  writeFileSync(filePath, content);
+  return filePath;
+}
+
+/** Writes exports under a kankaku dir resolved lazily against `fallbackCwd()` at call time. */
+export class LazyExportWriter {
+  private readonly dirOrRelative: string;
+  private readonly fallbackCwd: () => string;
+
+  constructor(dirOrRelative: string, fallbackCwd: () => string = () => process.cwd()) {
+    this.dirOrRelative = dirOrRelative;
+    this.fallbackCwd = fallbackCwd;
+  }
+
+  write(name: string, content: string): string {
+    return writeExport(resolveKankakuDir(this.dirOrRelative, this.fallbackCwd()), name, content);
+  }
+}