kankaku-pi 1.0.0

package/src/adapters/pocketbase-catalog.ts

@@ -0,0 +1,89 @@
+import type { Client, HubTask, Project } from "../domain/work-target.ts";
+import type { PocketBaseClient, PocketBaseRecord } from "./pocketbase-client.ts";
+
+interface ClientRecord extends PocketBaseRecord {
+  name: string;
+  code: string;
+  active?: boolean;
+  unassigned?: boolean;
+}
+
+interface ProjectRecord extends PocketBaseRecord {
+  name: string;
+  code?: string;
+  client: string;
+  repo_paths?: unknown;
+  active?: boolean;
+}
+
+interface TaskRecord extends PocketBaseRecord {
+  title?: string;
+  project: string;
+  status?: string;
+  external_ref?: string;
+}
+
+const TASK_STATUSES = new Set(["open", "doing", "done"]);
+
+function mapClient(record: ClientRecord): Client {
+  return {
+    id: record.id,
+    name: record.name,
+    code: record.code,
+    active: record.active === true,
+    ...(record.unassigned === true ? { unassigned: true } : {}),
+  };
+}
+
+function mapProject(record: ProjectRecord): Project {
+  return {
+    id: record.id,
+    name: record.name,
+    ...(record.code !== undefined ? { code: record.code } : {}),
+    clientId: record.client,
+    repoPaths: Array.isArray(record.repo_paths) ? record.repo_paths.filter((path): path is string => typeof path === "string") : [],
+    active: record.active === true,
+  };
+}
+
+/** `open` on any unrecognised or missing status, rather than dropping the task. */
+function mapTaskStatus(status: string | undefined): HubTask["status"] {
+  return status !== undefined && TASK_STATUSES.has(status) ? (status as HubTask["status"]) : "open";
+}
+
+function mapTask(record: TaskRecord): HubTask {
+  return {
+    id: record.id,
+    title: record.title ?? "",
+    projectId: record.project,
+    status: mapTaskStatus(record.status),
+    ...(typeof record.external_ref === "string" && record.external_ref !== "" ? { externalRef: record.external_ref } : {}),
+  };
+}
+
+/**
+ * Build the `fetchCatalog` function {@link CachedCatalog} (`cached-catalog.ts`)
+ * needs, backed by a {@link PocketBaseClient}. Fetches every `clients`,
+ * `projects` and `tasks` record in parallel (no `active`/`status` filter,
+ * so the domain resolver can tell "deleted" from "inactive"/"done"; see
+ * `domain/work-target.ts`), clients/projects sorted by name and tasks by
+ * title. `signal`, when given, bounds every fetch (see
+ * `pocketbase-client.ts#request`).
+ */
+export function createPocketBaseCatalogFetcher(
+  client: PocketBaseClient,
+): (signal?: AbortSignal) => Promise<{ clients: Client[]; projects: Project[]; tasks: HubTask[] }> {
+  return async (signal?: AbortSignal) => {
+    const [clientRecords, projectRecords, taskRecords] = await Promise.all([
+      client.list<ClientRecord>("clients", { sort: "name" }, signal),
+      client.list<ProjectRecord>("projects", { sort: "name" }, signal),
+      client.list<TaskRecord>("tasks", { sort: "title" }, signal),
+    ]);
+
+    return {
+      clients: clientRecords.map(mapClient),
+      projects: projectRecords.map(mapProject),
+      tasks: taskRecords.map(mapTask),
+    };
+  };
+}

package/src/adapters/pocketbase-client.ts

@@ -0,0 +1,197 @@
+/**
+ * Reusable, minimal PocketBase HTTP client: auth (with a single re-auth on
+ * 401), pagination, timeouts, and typed errors, built around an injected
+ * `fetch`. No pi imports, no domain knowledge — this is a general-purpose
+ * adapter meant to be reused by the sync push (a later phase) for
+ * create/update calls through the same `request()` primitive.
+ */
+
+export type PocketBaseFetch = typeof fetch;
+
+export interface PocketBaseRecord {
+  id: string;
+  [key: string]: unknown;
+}
+
+export interface PocketBaseListResult<T> {
+  page: number;
+  perPage: number;
+  totalItems: number;
+  totalPages: number;
+  items: T[];
+}
+
+export interface PocketBaseClientOptions {
+  /** Base URL, e.g. `https://pb.example.com` (no trailing slash required). */
+  url: string;
+  email: string;
+  password: string;
+  /** Injectable for tests; defaults to `globalThis.fetch`. */
+  fetch?: PocketBaseFetch;
+  /** Per-request timeout in ms. Defaults to 3000. */
+  timeoutMs?: number;
+}
+
+export type PocketBaseErrorKind = "network" | "timeout" | "http" | "auth";
+
+export class PocketBaseError extends Error {
+  readonly kind: PocketBaseErrorKind;
+  readonly status: number | undefined;
+
+  constructor(kind: PocketBaseErrorKind, message: string, status?: number) {
+    super(message);
+    this.name = "PocketBaseError";
+    this.kind = kind;
+    this.status = status;
+  }
+}
+
+interface AuthResponse {
+  token: string;
+  record: PocketBaseRecord;
+}
+
+const DEFAULT_TIMEOUT_MS = 3000;
+const AUTH_PATH = "/api/collections/users/auth-with-password";
+
+function isAbortError(error: unknown): boolean {
+  return error instanceof Error && error.name === "AbortError";
+}
+
+/** Build a `records` list path with pagination/filter/sort query params. */
+function listPath(collection: string, page: number, perPage: number, filter?: string, sort?: string): string {
+  const params = new URLSearchParams({ page: String(page), perPage: String(perPage) });
+  if (filter) params.set("filter", filter);
+  if (sort) params.set("sort", sort);
+  return `/api/collections/${encodeURIComponent(collection)}/records?${params.toString()}`;
+}
+
+/**
+ * Minimal PocketBase client: lazily authenticates on the first request,
+ * reuses the token, and re-authenticates exactly once on a 401 before
+ * failing cleanly. `request` is the generic primitive other adapters (and
+ * a future sync sink) build on; `list` is a pagination convenience for
+ * read-only catalog fetches.
+ */
+export class PocketBaseClient {
+  private readonly baseUrl: string;
+  private readonly email: string;
+  private readonly password: string;
+  private readonly doFetch: PocketBaseFetch;
+  private readonly timeoutMs: number;
+  private token: string | undefined;
+  /** Single-flight guard: concurrent callers with no token share this in-flight authentication instead of each posting their own. Cleared on settle (success or failure) so a failed auth never poisons a later attempt. */
+  private authInFlight: Promise<void> | undefined;
+
+  constructor(options: PocketBaseClientOptions) {
+    this.baseUrl = options.url.replace(/\/+$/, "");
+    this.email = options.email;
+    this.password = options.password;
+    this.doFetch = options.fetch ?? fetch;
+    this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  }
+
+  /** Perform `request` with the current token (authenticating first if there is none). `signal` bounds the underlying fetch when starting a fresh authentication; ignored by a caller that joins one already in flight. */
+  private authenticate(signal?: AbortSignal): Promise<void> {
+    if (!this.authInFlight) {
+      this.authInFlight = this.doAuthenticate(signal).finally(() => {
+        this.authInFlight = undefined;
+      });
+    }
+    return this.authInFlight;
+  }
+
+  private async doAuthenticate(signal?: AbortSignal): Promise<void> {
+    const response = await this.rawFetch("POST", AUTH_PATH, { identity: this.email, password: this.password }, undefined, signal);
+    if (!response.ok) {
+      throw new PocketBaseError("auth", `kankaku: hub authentication failed (${response.status})`, response.status);
+    }
+    const body = (await response.json()) as AuthResponse;
+    this.token = body.token;
+  }
+
+  /** `signal`, when given, is composed with this call's own per-request timeout signal (`AbortSignal.any`) so a caller can additionally bound a whole sequence of calls with one overall deadline. */
+  private async rawFetch(method: string, path: string, body: unknown, token: string | undefined, signal?: AbortSignal): Promise<Response> {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    const requestSignal = signal ? AbortSignal.any([controller.signal, signal]) : controller.signal;
+    try {
+      return await this.doFetch(`${this.baseUrl}${path}`, {
+        method,
+        headers: {
+          "content-type": "application/json",
+          ...(token !== undefined ? { Authorization: token } : {}),
+        },
+        ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        signal: requestSignal,
+      });
+    } catch (error) {
+      if (isAbortError(error)) {
+        throw new PocketBaseError("timeout", `kankaku: hub request timed out after ${this.timeoutMs}ms: ${method} ${path}`);
+      }
+      throw new PocketBaseError("network", `kankaku: hub request failed: ${method} ${path}: ${(error as Error).message}`);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  /**
+   * Generic request primitive: `method`/`path` (e.g. `/api/collections/clients/records`)
+   * with an optional JSON `body`. Authenticates lazily, retries exactly
+   * once on a 401 after re-authenticating, and throws a typed
+   * {@link PocketBaseError} on network failure, timeout, auth failure, or
+   * any other non-2xx response. `signal`, when given, is composed with
+   * every underlying request's own per-request timeout, so a caller can
+   * bound this whole call (including a lazy auth and the 401 retry) with
+   * one overall deadline; an abort surfaces as a `"timeout"` error, same as
+   * a per-request timeout.
+   */
+  async request<T = unknown>(method: string, path: string, body?: unknown, signal?: AbortSignal): Promise<T> {
+    if (this.token === undefined) {
+      await this.authenticate(signal);
+    }
+
+    let response = await this.rawFetch(method, path, body, this.token, signal);
+
+    if (response.status === 401) {
+      this.token = undefined;
+      await this.authenticate(signal);
+      response = await this.rawFetch(method, path, body, this.token, signal);
+    }
+
+    if (!response.ok) {
+      if (response.status === 401) {
+        throw new PocketBaseError("auth", `kankaku: hub rejected credentials for ${method} ${path}`, response.status);
+      }
+      throw new PocketBaseError("http", `kankaku: hub request failed: ${method} ${path} (${response.status})`, response.status);
+    }
+
+    if (response.status === 204) return undefined as T;
+    return (await response.json()) as T;
+  }
+
+  /**
+   * Fetch every record of `collection`, paginating until every page is
+   * read. `perPage` defaults to 200; `filter`/`sort` are passed through
+   * verbatim as PocketBase filter/sort expressions. `signal`, when given,
+   * bounds the whole pagination loop (see {@link request}).
+   */
+  async list<T extends PocketBaseRecord = PocketBaseRecord>(
+    collection: string,
+    opts: { filter?: string; sort?: string; perPage?: number } = {},
+    signal?: AbortSignal,
+  ): Promise<T[]> {
+    const perPage = opts.perPage ?? 200;
+    const items: T[] = [];
+    let page = 1;
+
+    for (;;) {
+      const result = await this.request<PocketBaseListResult<T>>("GET", listPath(collection, page, perPage, opts.filter, opts.sort), undefined, signal);
+      items.push(...result.items);
+      if (page >= result.totalPages || result.items.length === 0) break;
+      page += 1;
+    }
+
+    return items;
+  }
+}

package/src/adapters/pocketbase-sink.ts

@@ -0,0 +1,236 @@
+/**
+ * {@link WorkSink} backed by a real PocketBase instance: upserts one
+ * `task_entries` row per task (create-only assignment, see
+ * `domain/hub-entry.ts`) and, when enabled, its `work_records` children.
+ *
+ * PocketBase has no native upsert (contract.md "Upsert by task_id"): look
+ * up existing rows by their unique key in chunks, then create or patch.
+ * A unique-violation on create (approximated here as any 400 on create,
+ * since `PocketBaseError` does not carry the response body — see the
+ * `isLikelyUniqueViolation` note below) is treated as "already exists":
+ * look it up and patch instead.
+ */
+
+import { buildTaskEntryCreatePayload, buildTaskEntryUpdatePayload, buildWorkRecordPayload, resolveTaskAssignment, taskWorkRecords } from "../domain/hub-entry.ts";
+import type { PromptPrivacyMode } from "../domain/hub-entry.ts";
+import type { TaskView } from "../domain/task-view.ts";
+import type { Client, HubTask, Project } from "../domain/work-target.ts";
+import type { PushOutcome, PushTaskResult, WorkSink } from "../ports/work-sink.ts";
+import type { PocketBaseClient, PocketBaseRecord } from "./pocketbase-client.ts";
+import { PocketBaseError } from "./pocketbase-client.ts";
+
+export interface PocketBaseSinkDeps {
+  client: PocketBaseClient;
+  /** Catalog snapshot to resolve assignment against; see `domain/hub-entry.ts#resolveTaskAssignment`. */
+  clients: Client[];
+  projects: Project[];
+  tasks: HubTask[];
+  machine: string;
+  promptMode: PromptPrivacyMode;
+  /** Coding agent that produced these rows; see `domain/hub-entry.ts#HubEntryContext.agent`. Defaults to `"pi"`. */
+  agent?: string;
+  agentVersion?: string;
+  /** The integration that wrote these rows; see `domain/hub-entry.ts#HubEntryContext.plugin`. Defaults to `"kankaku"`. */
+  plugin?: string;
+  pluginVersion?: string;
+  /** `KANKAKU_SYNC_RECORDS` (default enabled): also upsert each task's raw `work_records`. */
+  syncRecords: boolean;
+  /** ids per lookup request. Defaults to 30, per contract.md's guidance. */
+  chunkSize?: number;
+}
+
+const DEFAULT_CHUNK_SIZE = 30;
+
+/** Escape a value for PocketBase's filter string-literal syntax (`field="value"`). Exported for direct unit testing. */
+export function escapeFilterValue(value: string): string {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+
+/** Fatal (systemic) errors stop the whole sync run rather than failing one task. */
+function isFatalError(error: unknown): boolean {
+  if (!(error instanceof PocketBaseError)) return true;
+  if (error.kind === "network" || error.kind === "timeout" || error.kind === "auth") return true;
+  if (error.kind === "http" && error.status !== undefined && error.status >= 500) return true;
+  return false;
+}
+
+function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * `PocketBaseError` for a create only carries `status`/`kind`, not the
+ * parsed response body, so we cannot check `data.<field>.code ===
+ * "validation_not_unique"` directly (contract.md "What a unique-violation
+ * response actually looks like"). Instead, any 400 on a create is treated
+ * as a possible race and re-looked-up: if the row now exists, it was a
+ * duplicate (patch it); if not, it was a genuine validation error (the
+ * original message is kept).
+ */
+function isLikelyUniqueViolation(error: unknown): boolean {
+  return error instanceof PocketBaseError && error.kind === "http" && error.status === 400;
+}
+
+export class PocketBaseSink implements WorkSink {
+  private readonly deps: PocketBaseSinkDeps;
+
+  constructor(deps: PocketBaseSinkDeps) {
+    this.deps = deps;
+  }
+
+  private get chunkSize(): number {
+    return this.deps.chunkSize ?? DEFAULT_CHUNK_SIZE;
+  }
+
+  /** Look up existing records by a unique field, chunked to ~30 ids per request; returns a map of that field's value to the record's PocketBase id. */
+  private async lookupExisting(collection: string, field: string, values: string[]): Promise<Map<string, string>> {
+    const found = new Map<string, string>();
+    const chunkSize = this.chunkSize;
+
+    for (let i = 0; i < values.length; i += chunkSize) {
+      const chunk = values.slice(i, i + chunkSize);
+      if (chunk.length === 0) continue;
+      const filter = chunk.map((value) => `${field}="${escapeFilterValue(value)}"`).join("||");
+      const items = await this.deps.client.list<PocketBaseRecord & Record<string, unknown>>(collection, { filter, perPage: chunkSize });
+      for (const item of items) {
+        const value = item[field];
+        if (typeof value === "string") found.set(value, item.id);
+      }
+    }
+
+    return found;
+  }
+
+  private async findOne(collection: string, field: string, value: string): Promise<string | undefined> {
+    const found = await this.lookupExisting(collection, field, [value]);
+    return found.get(value);
+  }
+
+  private get entryContext(): {
+    clients: Client[];
+    projects: Project[];
+    tasks: HubTask[];
+    machine: string;
+    promptMode: PromptPrivacyMode;
+    agent: string;
+    agentVersion?: string;
+    plugin: string;
+    pluginVersion?: string;
+  } {
+    return {
+      clients: this.deps.clients,
+      projects: this.deps.projects,
+      tasks: this.deps.tasks,
+      machine: this.deps.machine,
+      promptMode: this.deps.promptMode,
+      agent: this.deps.agent ?? "pi",
+      ...(this.deps.agentVersion !== undefined ? { agentVersion: this.deps.agentVersion } : {}),
+      plugin: this.deps.plugin ?? "kankaku",
+      ...(this.deps.pluginVersion !== undefined ? { pluginVersion: this.deps.pluginVersion } : {}),
+    };
+  }
+
+  /** Create-or-patch one task_entries row. Returns its PocketBase record id and whether it was created or updated. */
+  private async upsertTaskEntry(task: TaskView, existingId: string | undefined): Promise<{ id: string; created: boolean }> {
+    const ctx = this.entryContext;
+
+    if (existingId) {
+      await this.deps.client.request("PATCH", `/api/collections/task_entries/records/${existingId}`, buildTaskEntryUpdatePayload(task, ctx));
+      return { id: existingId, created: false };
+    }
+
+    try {
+      const created = await this.deps.client.request<PocketBaseRecord>(
+        "POST",
+        "/api/collections/task_entries/records",
+        buildTaskEntryCreatePayload(task, ctx),
+      );
+      return { id: created.id, created: true };
+    } catch (error) {
+      if (!isLikelyUniqueViolation(error)) throw error;
+      const found = await this.findOne("task_entries", "task_id", task.id);
+      if (!found) throw error;
+      await this.deps.client.request("PATCH", `/api/collections/task_entries/records/${found}`, buildTaskEntryUpdatePayload(task, ctx));
+      return { id: found, created: false };
+    }
+  }
+
+  /** Best-effort upsert of one task's work_records children. A per-record validation failure is swallowed (the task_entries row already succeeded); a fatal error propagates so the whole run stops. */
+  private async upsertWorkRecords(task: TaskView, taskEntryRecordId: string): Promise<void> {
+    const records = taskWorkRecords(task);
+    const existing = await this.lookupExisting(
+      "work_records",
+      "kankaku_id",
+      records.map((record) => record.id),
+    );
+
+    for (const record of records) {
+      const payload = buildWorkRecordPayload(record, taskEntryRecordId, { machine: this.deps.machine, promptMode: this.deps.promptMode });
+      const existingId = existing.get(record.id);
+      try {
+        if (existingId) {
+          await this.deps.client.request("PATCH", `/api/collections/work_records/records/${existingId}`, payload);
+        } else {
+          try {
+            await this.deps.client.request("POST", "/api/collections/work_records/records", payload);
+          } catch (error) {
+            if (!isLikelyUniqueViolation(error)) throw error;
+            const found = await this.findOne("work_records", "kankaku_id", record.id);
+            if (!found) throw error;
+            await this.deps.client.request("PATCH", `/api/collections/work_records/records/${found}`, payload);
+          }
+        }
+      } catch (error) {
+        if (isFatalError(error)) throw error;
+        // Non-fatal: this one child row failed validation; the task_entries
+        // row it belongs to already succeeded, so skip it and keep going.
+      }
+    }
+  }
+
+  private async pushOne(task: TaskView, existingId: string | undefined): Promise<PushOutcome> {
+    const assignment = resolveTaskAssignment(task, this.deps.clients, this.deps.projects, this.deps.tasks);
+    const pushAssignment = { unassigned: assignment.routedToUnassigned, ...(assignment.legacyClientLabel ? { legacyLabel: assignment.legacyClientLabel } : {}) };
+
+    try {
+      const { id, created } = await this.upsertTaskEntry(task, existingId);
+
+      if (this.deps.syncRecords) {
+        await this.upsertWorkRecords(task, id);
+      }
+
+      return created ? { kind: "created", ...pushAssignment } : { kind: "updated", ...pushAssignment };
+    } catch (error) {
+      if (isFatalError(error)) return { kind: "error", reason: describeError(error) };
+      return { kind: "failed", reason: describeError(error) };
+    }
+  }
+
+  async push(tasks: TaskView[]): Promise<PushTaskResult[]> {
+    const results: PushTaskResult[] = [];
+    if (tasks.length === 0) return results;
+
+    // One chunked lookup for every task up front (contract.md: "one list
+    // request per ~30 ids"), rather than one lookup per task.
+    let existingByTaskId: Map<string, string>;
+    try {
+      existingByTaskId = await this.lookupExisting(
+        "task_entries",
+        "task_id",
+        tasks.map((task) => task.id),
+      );
+    } catch (error) {
+      const outcome: PushOutcome = isFatalError(error) ? { kind: "error", reason: describeError(error) } : { kind: "failed", reason: describeError(error) };
+      results.push({ taskId: tasks[0]!.id, outcome });
+      return results;
+    }
+
+    for (const task of tasks) {
+      const outcome = await this.pushOne(task, existingByTaskId.get(task.id));
+      results.push({ taskId: task.id, outcome });
+      if (outcome.kind === "error") break;
+    }
+
+    return results;
+  }
+}

package/src/adapters/process-identity-memo.ts

@@ -0,0 +1,102 @@
+import { resolveProcessIdentity } from "./process-identity.ts";
+import type { ProcessIdentity, ResolveProcessIdentityDeps } from "./process-identity.ts";
+
+/**
+ * Freezes {@link resolveProcessIdentity}'s result for the lifetime of one
+ * OS process (G1, HIGH — verified): pi re-invokes an extension's factory
+ * function IN THE SAME OS PROCESS on `/new`, `/resume`, `/fork` and
+ * `/reload` ("reloads and rebinds extensions for the new session" — see
+ * `node_modules/@earendil-works/pi-coding-agent/docs/extensions.md`). Every
+ * fact `resolveProcessIdentity` computes is about the OS PROCESS, not the
+ * pi session running inside it, and several of them can only ever be read
+ * correctly once:
+ *
+ * - `roleOverride` (`KANKAKU_ROLE`, read before this call strips it from
+ *   `process.env` so no spawned child ever inherits it — R1, layer 2): a
+ *   second invocation would read `undefined` (already stripped by the
+ *   first), silently losing an explicit `KANKAKU_ROLE=orchestrator` force —
+ *   exactly the bug this module fixes. Without freezing, a forced
+ *   orchestrator whose process happens to have a tracked ancestor (e.g. it
+ *   was itself launched from inside another pi's shell tool) would fall
+ *   back to ordinary detection on session 2 and could be demoted to
+ *   `roleConfidence: "uncertain"`, silently dropping genuine billable work.
+ * - `hasTrackedAncestor`/`ancestorEntry` (the machine-wide registry +
+ *   OS-ancestor-chain walk, F5): this process's ancestor chain is fixed at
+ *   OS-process-creation time and does not change for the life of the
+ *   process; re-walking it on every reload would also re-spawn a `ps`/
+ *   `/proc` read each time for no benefit (F5's whole point is to avoid
+ *   exactly that).
+ * - `ownProcessStartId` (F5's spawn-free own-identity estimate,
+ *   `now - uptime`): a fresh reading on invocation 2 is a slightly
+ *   different point-estimate of the same real start time as invocation 1's
+ *   — usually well within `ancestry-match.ts#START_ID_TOLERANCE_MS`, but
+ *   several `process.on("exit")` listeners (see below) each holding a
+ *   *different* estimate risk `removeOwn`'s exact-match check silently
+ *   failing to clean up the registry entry the LAST `record()` call
+ *   actually wrote. Freezing it means every invocation's registry write —
+ *   and any later cleanup — always agrees on the exact same value.
+ *
+ * Session-level facts are deliberately NOT frozen here and must be
+ * re-evaluated by the caller every invocation: interactive mode from
+ * `ctx.mode` (only known later, at `session_start`), and the session's
+ * project/client target (`process.cwd()` can legitimately differ between
+ * sessions in the same process — see `extensions.md`'s trust-resolution
+ * note on `/resume` entering a new cwd — so `extension.ts` still calls
+ * `resolveKankakuDir` fresh every invocation).
+ *
+ * Kept as a small, explicitly injectable holder (never module-level mutable
+ * state read directly by a domain type) so a test can construct its own
+ * memo, and so production code goes through exactly one shared, real
+ * process-wide instance (see {@link getProcessIdentityMemo}).
+ */
+export interface ProcessIdentityMemo {
+  /**
+   * Returns the frozen facts, computing them (and freezing whatever they
+   * are) on the first call this memo instance ever receives; every later
+   * call ignores `deps` entirely and returns the exact same object.
+   */
+  resolve(deps: ResolveProcessIdentityDeps): ProcessIdentity;
+  /**
+   * Registers `cleanup` with `on` at most once across every call this memo
+   * instance ever receives — the fix for the sibling leak this finding
+   * flagged: `extension.ts` used to call `process.on("exit", ...)`
+   * unconditionally on every factory invocation, piling up one listener per
+   * `/new`/`/resume`/`/fork`/`/reload` (each running `removeOwn`
+   * needlessly, though harmlessly, since it is idempotent — the real risk
+   * is an unbounded listener count over a long-lived interactive session).
+   * `on` takes the listener directly (never the event name) so a test can
+   * inject a plain recording function instead of touching the real
+   * `process` object.
+   */
+  registerExitCleanupOnce(on: (listener: () => void) => void, cleanup: () => void): void;
+}
+
+export function createProcessIdentityMemo(): ProcessIdentityMemo {
+  let facts: ProcessIdentity | undefined;
+  let exitCleanupRegistered = false;
+
+  return {
+    resolve(deps: ResolveProcessIdentityDeps): ProcessIdentity {
+      if (facts === undefined) facts = resolveProcessIdentity(deps);
+      return facts;
+    },
+    registerExitCleanupOnce(on: (listener: () => void) => void, cleanup: () => void): void {
+      if (exitCleanupRegistered) return;
+      exitCleanupRegistered = true;
+      on(cleanup);
+    },
+  };
+}
+
+// The real, process-wide singleton `extension.ts` uses in production: one
+// module-level instance, reused by every factory invocation in this OS
+// process — which is the entire point (see the class doc above). A test
+// must never rely on this singleton (module state would leak between test
+// files run in the same worker); construct a fresh memo via
+// `createProcessIdentityMemo()` instead.
+let processWideMemo: ProcessIdentityMemo = createProcessIdentityMemo();
+
+/** The real, process-wide {@link ProcessIdentityMemo} `extension.ts` reads and writes on every factory invocation. */
+export function getProcessIdentityMemo(): ProcessIdentityMemo {
+  return processWideMemo;
+}