@runuai/host 0.9.150 → 0.9.152

package/lib/credentials-purge.ts

@@ -0,0 +1,1006 @@
+/**
+ * ADR-154 §13: the runner's local credential stores are removed.
+ *
+ * The activation authority calls `purgeLocalCredentialStores` once the cloud
+ * has committed this runner to cloud credentials, after the runner has left
+ * its own (cloud-credential-host.ts `leaveLegacy`), and before it advertises
+ * v1. It deletes what §13 lists:
+ * - project env values and records (`host_project_env*`), and the value
+ *   tables of a task machine's replica (`host_project_env_replica*`);
+ * - AI accounts: `host_engine_accounts`, and the account directories Uai
+ *   created under the owner's home;
+ * - MCP connections, their secrets and pending OAuth state;
+ * - GitHub tokens and their generation fence, SSH keys, and any per-task
+ *   decrypted SSH key a crash left in the data dir;
+ * - the engine keys Uai wrote into `.env.local`, and this process's copies;
+ * - the broker's sidecars, and credential-store writes a dead process left
+ *   staged with a value in them;
+ * and, beyond those stores, what still holds a credential: each task's
+ * `uai` CLI secret and MCP gateway token in the data dir, the GitHub PAT
+ * fallback (from `.env.local` and this process, as the engine keys), and the
+ * GitHub tokens this process holds in memory. The database's deletes run
+ * with `secure_delete` on, then it vacuums and truncates the WAL, so that no
+ * freed page keeps any of them.
+ *
+ * The operator's own sign-ins stay (`~/.codex`, `~/.grok`, OpenCode's data
+ * dir, `~/.kimi-code`, `~/.claude.json`, Claude's keychain): only the
+ * broker's sidecar leaves them. So do the runner's own secrets (its
+ * enrollment, `host-master.key`, the ADR-153 CA) and every task's worktree.
+ * An account's directory goes only from where Uai makes it; an account row
+ * naming any other path stays, and fails the purge. Nothing is removed
+ * through a symbolic link below the owner's home or the data dir: what the
+ * purge would remove, found only behind one, stays and fails the purge, as
+ * does a link there that leads to nothing. Nor does it remove one name of
+ * what has another: a link where it removes something, a link in what it
+ * removes that leads out of it, and a file with a second (hard) name each
+ * stay, and fail it, for the runner's own writes went through them. Absence
+ * behind a link proves nothing: an account row's directory missing behind
+ * one, and a store of Uai's own reached through one, fail it. Absence with no
+ * link on the way counts, so storage detached at its own mount point while
+ * the purge runs is not seen (accepted, ADR-154 §13). `.env.local`
+ * loses its keys only from a regular file of a settings file's size, and a
+ * link of it, or a directory above it, that leads to nothing fails the purge
+ * too.
+ *
+ * A crash anywhere is resumed by calling it again, and a call after a
+ * complete one removes nothing. Every step is attempted; if anything could
+ * not be removed it then throws, and the runner stays activation-pending.
+ * No value is logged, returned or thrown: only table names, account ids,
+ * paths, key names and counts.
+ */
+
+import {
+  closeSync,
+  constants,
+  fstatSync,
+  lstatSync,
+  openSync,
+  readdirSync,
+  readlinkSync,
+  readSync,
+  realpathSync,
+  rmSync,
+  statSync,
+  type BigIntStats,
+  type Dirent,
+  type Stats,
+} from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { parseEnv } from "node:util";
+
+import { eq, getTableName, notInArray } from "drizzle-orm";
+import type { SQLiteTable } from "drizzle-orm/sqlite-core";
+
+import { onOwnCredentials } from "./cloud-credential-host";
+import { memoryBackedDir, removeStagedWritesLeftBehind } from "./credential-store";
+import { getDb, schema, withHostSqlite } from "./db";
+import { BROKER_SIDECAR_FILE } from "./engine-accounts";
+import { env } from "./env";
+import { keysQuotedPastTheirLine, serializeEnvFileMutation, withoutEnvKeys, writeDurableFileAtomic } from "./env-file";
+import { assertNoAliases } from "./fs-aliases";
+import { forgetGithubTokensInMemory } from "./github-tokens";
+import { noteProjectEnvAuthorityChange } from "./host-env";
+
+/** What `.env.local` and this process lose: exactly the engine keys §13
+ *  names, and the GitHub PAT fallback (github-tokens.ts `setupTaskGithub`).
+ *  Every other line stays, `UAI_GH_PAT_FALLBACK_USER_ID` too: a user id,
+ *  inert without the PAT. */
+const ENV_CREDENTIAL_KEYS = [
+  "CLAUDE_CODE_OAUTH_TOKEN",
+  "ANTHROPIC_API_KEY",
+  "ANTHROPIC_AUTH_TOKEN",
+  "XAI_API_KEY",
+  "CURSOR_API_KEY",
+  "UAI_GH_PAT_FALLBACK",
+] as const;
+
+/** Where Uai makes a config-dir account's directory, by the row's kind
+ *  (engine-accounts.ts `extraHostDir`): in the owner's home, the kind's
+ *  prefix and then the row's own id. Both of Uai's writers of these rows (a
+ *  new account, and one imported from the credential store) record exactly
+ *  that path, and neither a row's kind nor its path changes after. */
+const ACCOUNT_LAYOUTS: ReadonlyMap<string, { parent: readonly string[]; prefix: string }> = new Map<
+  string,
+  { parent: readonly string[]; prefix: string }
+>([
+  ["codex", { parent: [], prefix: ".codex-acct-" }],
+  ["grok", { parent: [], prefix: ".grok-acct-" }],
+  ["opencode", { parent: [".local", "share"], prefix: "opencode-acct-" }],
+]);
+
+/** An account id as it ends one of those names: a single path segment (a
+ *  ULID, or a credential-store path segment). An id with a `/` in it would
+ *  make the layout itself name a path out of the owner's home. */
+const ACCOUNT_ID = /^[A-Za-z0-9_.-]+$/;
+
+/** The operator's own engine dirs the broker kept a sidecar in
+ *  (token-broker-local.ts `DEFAULT_SLOTS`). Only the sidecar leaves them. */
+const OPERATOR_SIDECAR_DIRS = [".codex", ".grok"] as const;
+
+export interface CredentialsPurgeReport {
+  /** Rows deleted, by table. */
+  rows: Record<string, number>;
+  /** Directories removed: AI accounts', per-task SSH identities, staged
+   *  credential-store writes. */
+  dirs: string[];
+  /** Files removed: the broker's sidecars in the operator's own dirs, and
+   *  each task's CLI secret and MCP gateway token. */
+  files: string[];
+  /** Credential keys removed from `.env.local` or from this process's env. */
+  envKeys: string[];
+}
+
+export interface CredentialsPurgeOptions {
+  /** The home Uai created account dirs in. Default: as engine-accounts.ts
+   *  resolves it. */
+  ownerHome?: string;
+  /** Default: `.env.local` in the runner's home. */
+  envFile?: string;
+  /** Where per-task SSH identities, CLI secrets and MCP gateway tokens were
+   *  written. Default: the runner's data dir. The database is `getDb()`'s
+   *  whatever this says. */
+  dataDir?: string;
+  /** Tests only: where staged credential-store writes are looked for. */
+  stagingRoots?: readonly string[];
+}
+
+/** Not everything could be removed. `errors` say what, `report` what this
+ *  attempt did remove; calling the purge again resumes it. */
+export class CredentialsPurgeError extends AggregateError {
+  constructor(
+    errors: Error[],
+    readonly report: CredentialsPurgeReport,
+  ) {
+    super(errors, `the runner's local credential stores were not all removed (${errors.length} failed)`);
+    this.name = "CredentialsPurgeError";
+  }
+}
+
+type Fail = (what: string, error: unknown) => void;
+
+export async function purgeLocalCredentialStores(
+  options: CredentialsPurgeOptions = {},
+): Promise<CredentialsPurgeReport> {
+  // Irreversible: a runner still on its own credentials would lose them
+  // from under its live tasks.
+  if (onOwnCredentials()) {
+    throw new Error("the runner is still on its own credentials; its stores are not purged");
+  }
+  const ownerHome = resolve(options.ownerHome ?? (process.env.UAI_OWNER_HOME?.trim() || homedir()));
+  const envFile = options.envFile ?? join(env.uaiHome, ".env.local");
+  const dataDir = options.dataDir ?? env.dataDir;
+  const report: CredentialsPurgeReport = { rows: {}, dirs: [], files: [], envKeys: [] };
+  const failures: Error[] = [];
+  const fail: Fail = (what, error) => {
+    const reason = error instanceof Error ? error.message : String(error);
+    failures.push(new Error(`${what}: ${reason}`, { cause: error }));
+  };
+
+  // The one step that waits, first: it queues behind any other writer of
+  // `.env.local`. What follows runs in a single turn, so nothing can add a
+  // row between the account rows read below and the transaction that
+  // deletes them.
+  await removeEnvCredentialKeys(envFile, report, fail);
+
+  const accounts = readAccountRows(fail);
+  const accountRowsKept = accounts === null ? null : removeAccountDirs(ownerHome, accounts, report, fail);
+  removeSidecars(ownerHome, report, fail);
+  removeTaskIdentities(dataDir, report, fail);
+  removeTaskSecrets(dataDir, report, fail);
+  removeStagedWrites(options.stagingRoots ?? defaultStagingRoots(), report, fail);
+  purgeDatabase(accountRowsKept, report, fail);
+  // After the rows: no exchange can start from one again.
+  forgetGithubTokens(fail);
+
+  if (failures.length > 0) throw new CredentialsPurgeError(failures, report);
+  return report;
+}
+
+/**
+ * The credential keys, from `.env.local` and from this process.
+ *
+ * The file loses them where it is. src/load-env.ts reads `.env.local`
+ * through any link, so a linked one (into a dotfiles checkout, say) has its
+ * keys in the file at the end of the links, and renaming a new file over
+ * the link, all a plain rewrite does, would replace the link and leave that
+ * file holding them. So the links are resolved, and the file at their end
+ * is rewritten atomically in its own directory (writeDurableFileAtomic: a
+ * temporary file beside it, then the rename over it); every link still
+ * names it. This rather than failing: a failure would keep the runner
+ * pending, running no task, until the operator made an edit the runner can
+ * make safely itself, dropping only these keys' lines from a file it reads
+ * at every boot. When it cannot (a directory it may not write, something
+ * that is not a settings file), it fails, naming both paths.
+ *
+ * A link that leads to nothing fails too, naming its target. No file holds
+ * the keys now, but the one it names may come back with them (a volume
+ * mounted again, a checkout restored), and the next boot would load them
+ * while nothing would run the purge again. So the purge stays failed until
+ * the operator removes the link or brings the file back. No `.env.local`
+ * at all, file or link, is nothing to do.
+ */
+async function removeEnvCredentialKeys(
+  envFile: string,
+  report: CredentialsPurgeReport,
+  fail: Fail,
+): Promise<void> {
+  const removed = new Set<string>();
+  let where = envFile;
+  try {
+    // Every writer of `.env.local` queues on this path, link or not. The
+    // links are resolved in this turn: one before it may have replaced them.
+    const fromFile = await serializeEnvFileMutation(envFile, () => {
+      const file = fileAtEndOfLinks(envFile);
+      if (file === null) return [];
+      if (file !== envFile) where = `${envFile} (through its links, ${file})`;
+      return removeKeysFromSettingsFile(file);
+    });
+    for (const key of fromFile) removed.add(key);
+  } catch (error) {
+    fail(`credential keys in ${where}`, error);
+  }
+  // Loaded at boot (src/load-env.ts), and read from here as the runner's own
+  // sign-in whatever the file says now.
+  for (const key of ENV_CREDENTIAL_KEYS) {
+    if (process.env[key] === undefined) continue;
+    delete process.env[key];
+    removed.add(key);
+  }
+  report.envKeys = ENV_CREDENTIAL_KEYS.filter((key) => removed.has(key));
+}
+
+/** The file `path` is once every link is followed; null when there is no
+ *  file there and no link either, in a directory that is there. A directory
+ *  above it that is not (a link on the way that leads to nothing, a volume
+ *  not mounted) proves nothing: it may come back holding the file. */
+function fileAtEndOfLinks(path: string): string | null {
+  const file = realpathIfThere(path);
+  if (file !== null) return file;
+  if (lstatIfThere(path)?.isSymbolicLink()) {
+    throw new Error(
+      `a symbolic link to ${readlinkSync(path)} that leads to nothing; remove it, or bring back the file it names`,
+    );
+  }
+  if (realpathIfThere(dirname(path)) === null) {
+    throw new Error(
+      `${dirname(path)}, the directory it would be in, is not there (a link on the way that leads to nothing, ` +
+        "or a volume not mounted); bring it back",
+    );
+  }
+  return null;
+}
+
+/** The most `.env.local` may hold. A settings file is a few hundred bytes,
+ *  and this one is read whole. */
+const ENV_FILE_MAX_BYTES = 1024 * 1024;
+
+/** Drops the credential keys from `file`, the file at the end of
+ *  `.env.local`'s links, and returns those it held. */
+function removeKeysFromSettingsFile(file: string): string[] {
+  const current = readSettingsFile(file);
+  // A value over several lines is never edited: the line that sets the key
+  // is not all of it, and which lines are depends on the parser (Node's has
+  // read them differently from one release to the next).
+  const runOn = keysQuotedPastTheirLine(current, ENV_CREDENTIAL_KEYS);
+  if (runOn.length > 0) {
+    throw new Error(
+      `${runOn.join(", ")} ${runOn.length === 1 ? "has a quoted value" : "have quoted values"} that ` +
+        "runs on past its line, whose rest dropping the line would leave; " +
+        `remove ${runOn.length === 1 ? "it" : "them"} by hand`,
+    );
+  }
+  const { body, removed } = withoutEnvKeys(current, ENV_CREDENTIAL_KEYS);
+  assertReadAsBefore(current, body, removed);
+  if (removed.length > 0) writeDurableFileAtomic(file, body);
+  return removed;
+}
+
+/**
+ * `file`'s text, when it is a regular file of a settings file's size. It is
+ * whatever the operator's links lead to, and the runner waits on this read:
+ * the purge runs synchronously. A FIFO with no writer would block the open
+ * forever, and a device such as /dev/zero would never end the read. So the
+ * open follows no link (one put there since the links were resolved fails
+ * it), does not wait (O_NONBLOCK: a FIFO opens at once) and takes no
+ * terminal as the runner's own (O_NOCTTY); what it opened is checked on the
+ * descriptor, so nothing can be swapped in between the check and the read;
+ * and the read stops past the limit, should the file have grown since.
+ * O_NOFOLLOW covers the file's own name only: a directory above it made a
+ * link in that instant would still be followed, by the open and by the
+ * rename after it, which Node has no openat to prevent.
+ */
+function readSettingsFile(file: string): string {
+  const descriptor = openSync(
+    file,
+    constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK | constants.O_NOCTTY,
+  );
+  try {
+    const stats = fstatSync(descriptor);
+    if (!stats.isFile()) throw new Error(`not a regular file but ${fileType(stats)}`);
+    // Rewritten, it is a new file under this name only: another name of the
+    // same file would keep the keys.
+    if (stats.nlink > 1) {
+      throw new Error(
+        `a file with ${stats.nlink} names (hard links); its keys would stay under the others: remove them, then the keys go`,
+      );
+    }
+    const tooLarge = () => new Error(`larger than ${ENV_FILE_MAX_BYTES} bytes, which no settings file is`);
+    if (stats.size > ENV_FILE_MAX_BYTES) throw tooLarge();
+    const buffer = Buffer.alloc(ENV_FILE_MAX_BYTES + 1);
+    let length = 0;
+    while (length < buffer.length) {
+      const read = readSync(descriptor, buffer, length, buffer.length - length, null);
+      if (read === 0) break;
+      length += read;
+    }
+    if (length > ENV_FILE_MAX_BYTES) throw tooLarge();
+    return buffer.toString("utf8", 0, length);
+  } finally {
+    closeSync(descriptor);
+  }
+}
+
+function fileType(stats: Stats): string {
+  if (stats.isDirectory()) return "a directory";
+  if (stats.isFIFO()) return "a FIFO";
+  if (stats.isCharacterDevice()) return "a character device";
+  if (stats.isBlockDevice()) return "a block device";
+  if (stats.isSocket()) return "a socket";
+  return "something else";
+}
+
+/**
+ * Throws, so that nothing is written, unless the runner will read `body` as
+ * it read `current` without the keys. src/load-env.ts loads the file with
+ * Node's own parser (process.loadEnvFile; util.parseEnv is that parser),
+ * which takes more than the one line, `KEY=value`, that withoutEnvKeys drops
+ * and Uai writes: `export KEY=value`, spaces about a key. A key set another
+ * way would stay, loaded at every boot while the purge counted it gone. (A
+ * key's quoted value over several lines was refused before this, by a rule
+ * of its own: what this parser makes of one has changed between releases.)
+ * Only the keys are named in the failure, never another setting: a line that
+ * is none is read as the start of the next setting's name, and may be a
+ * value.
+ */
+function assertReadAsBefore(current: string, body: string, removed: readonly string[]): void {
+  const after = parseEnv(body);
+  const left = ENV_CREDENTIAL_KEYS.filter((key) => Object.hasOwn(after, key));
+  if (left.length > 0) {
+    throw new Error(
+      `the runner would still load ${left.join(", ")} from what is left (not a KEY=value line); ` +
+        `remove ${left.length === 1 ? "it" : "them"} by hand`,
+    );
+  }
+  const before = parseEnv(current);
+  const credential = new Set<string>(ENV_CREDENTIAL_KEYS);
+  for (const name of new Set([...Object.keys(before), ...Object.keys(after)])) {
+    if (credential.has(name) || before[name] === after[name]) continue;
+    throw new Error(
+      `dropping the lines of ${removed.join(", ")} would change how the runner reads the rest of it; ` +
+        `remove ${removed.length === 1 ? "it" : "them"} by hand`,
+    );
+  }
+}
+
+interface AccountRow {
+  id: string;
+  kind: string;
+  configDir: string | null;
+}
+
+function readAccountRows(fail: Fail): AccountRow[] | null {
+  try {
+    return getDb()
+      .select({
+        id: schema.engineAccounts.id,
+        kind: schema.engineAccounts.kind,
+        configDir: schema.engineAccounts.configDir,
+      })
+      .from(schema.engineAccounts)
+      .all();
+  } catch (error) {
+    fail("AI account rows", error);
+    return null;
+  }
+}
+
+/**
+ * Every account directory Uai made. A row's directory goes, and the row
+ * with it, only when its path is exactly where Uai makes that account's
+ * (`accountDir`). Any other path, the operator's own `~/.codex` or a
+ * `.codex-acct-1` in some other directory alike, is left as it is: its row
+ * stays and the purge fails, naming both, so that no directory is forgotten
+ * that was not removed. Then any other directory in the owner's home named
+ * as Uai names one goes too, an orphan no row names. The directory a kind's
+ * are made in (the owner's home, or `.local/share` in it) is walked as
+ * `below` walks one: reached only through a link, nothing is removed from
+ * it, and each account directory behind the link fails, its row kept; a
+ * link on the way that leads to nothing keeps every row of that kind, and
+ * fails. Returns the ids of the rows that stay; the next call finds each
+ * again.
+ */
+function removeAccountDirs(
+  ownerHome: string,
+  rows: readonly AccountRow[],
+  report: CredentialsPurgeReport,
+  fail: Fail,
+): string[] {
+  const kept: string[] = [];
+  const named = new Set<string>();
+  // The rows whose directory is where Uai makes it, by kind.
+  const placed = new Map<string, Array<{ id: string; dir: string }>>();
+  for (const row of rows) {
+    if (row.configDir === null) continue;
+    named.add(row.configDir);
+    const dir = accountDir(ownerHome, row);
+    if (row.configDir !== dir) {
+      kept.push(row.id);
+      fail(
+        `account ${row.id}`,
+        new Error(
+          dir === null
+            ? `${row.configDir} is not a directory Uai makes; the row is kept`
+            : `${row.configDir} is not where Uai makes its directory (${dir}); the row is kept`,
+        ),
+      );
+      continue;
+    }
+    const ofKind = placed.get(row.kind) ?? [];
+    ofKind.push({ id: row.id, dir });
+    placed.set(row.kind, ofKind);
+  }
+  for (const [kind, { parent, prefix }] of ACCOUNT_LAYOUTS) {
+    const parentDir = join(ownerHome, ...parent);
+    const rowsHere = placed.get(kind) ?? [];
+    let where: Below;
+    try {
+      where = below(ownerHome, parent);
+    } catch (error) {
+      fail(parentDir, error);
+      kept.push(...rowsHere.map((row) => row.id));
+      continue;
+    }
+    if (where.kind === "none") {
+      // Missing on the way: every row's directory with it, proven only when
+      // no link came before (behind one, it may come back).
+      if (where.via !== undefined) {
+        for (const row of rowsHere) {
+          fail(`account ${row.id} at ${row.dir}`, notThereBehindLink(where.via));
+          kept.push(row.id);
+        }
+      }
+      continue;
+    }
+    // Each directory to remove, and the row it is (null: an orphan).
+    const dirs = new Map<string, string | null>(rowsHere.map((row) => [row.dir, row.id]));
+    for (const entry of listDir(where.path, fail)) {
+      if (!isAccountDirName(prefix, entry.name)) continue;
+      const path = join(parentDir, entry.name);
+      if (named.has(path)) continue;
+      // readdir's types are lstat's. A link named as Uai names an account's
+      // directory is never followed, and never removed alone: what it leads
+      // to may be an account's that Uai wrote through it.
+      if (entry.isSymbolicLink()) {
+        fail(path, new Error("a symbolic link named as Uai names an account's directory; neither it nor what it points at is removed"));
+        continue;
+      }
+      if (entry.isDirectory()) dirs.set(path, null);
+    }
+    for (const [path, rowId] of dirs) {
+      const gone =
+        where.kind === "dir"
+          ? removeAccountDir(path, rowId, where, report.dirs, fail)
+          : absentBehindLink(path, rowId, where, fail);
+      if (!gone && rowId !== null) kept.push(rowId);
+    }
+  }
+  return kept;
+}
+
+/** Where Uai makes this row's directory; null when it makes none (a kind
+ *  with no directory, or an id that is not one name). */
+function accountDir(ownerHome: string, row: AccountRow): string | null {
+  const layout = ACCOUNT_LAYOUTS.get(row.kind);
+  if (layout === undefined || !ACCOUNT_ID.test(row.id)) return null;
+  return join(ownerHome, ...layout.parent, `${layout.prefix}${row.id}`);
+}
+
+function isAccountDirName(prefix: string, name: string): boolean {
+  return name.startsWith(prefix) && ACCOUNT_ID.test(name.slice(prefix.length));
+}
+
+/** Removes an account directory (`rowId`'s, or an orphan's) as lstat finds
+ *  it, never through a link: the directories above it, in `where`, were
+ *  walked without following one, and are checked again just before. True
+ *  once it is gone. */
+function removeAccountDir(
+  path: string,
+  rowId: string | null,
+  where: ProvenDir,
+  into: string[],
+  fail: Fail,
+): boolean {
+  const what = rowId === null ? path : `account ${rowId} at ${path}`;
+  let stats: BigIntStats | null;
+  try {
+    stats = lstatIfThere(path);
+  } catch (error) {
+    fail(what, error);
+    return false;
+  }
+  if (stats === null) {
+    // Gone, if the directories above it are still the ones the walk found.
+    try {
+      assertUnmoved(where.chain);
+    } catch (error) {
+      fail(what, error);
+      return false;
+    }
+    return true;
+  }
+  if (stats.isSymbolicLink()) {
+    // Uai makes a directory here, never a link, yet its own writes would
+    // have gone through one (a recursive mkdir takes a link to a directory
+    // as made, and the account's files are written through it), so what it
+    // points at may hold the account's credentials. Removing only the link
+    // would forget them along with the row, and following it would let a
+    // link aim this recursive delete anywhere. So neither: the link, what it
+    // points at and the row all stay, and the purge fails until the link is
+    // gone.
+    fail(what, new Error("a symbolic link where Uai makes a directory; neither it nor what it points at is removed"));
+    return false;
+  }
+  try {
+    assertNoAliases(path);
+    assertUnmoved(where.chain);
+    rmSync(path, { recursive: true, force: true });
+  } catch (error) {
+    fail(what, error);
+    return false;
+  }
+  into.push(path);
+  return true;
+}
+
+/** An account directory reached only through a link (`where`): looked for,
+ *  never removed. A row's that is not there proves nothing behind a link,
+ *  and fails too; an orphan is one found there. True only when it was
+ *  never Uai's to look for. */
+function absentBehindLink(path: string, rowId: string | null, where: LinkedDir, fail: Fail): boolean {
+  const what = rowId === null ? path : `account ${rowId} at ${path}`;
+  try {
+    if (lstatIfThere(path) !== null) fail(what, throughLink(where));
+    else if (rowId !== null) fail(what, notThereBehindLink(where));
+    else return true;
+  } catch (error) {
+    fail(what, error);
+  }
+  return false;
+}
+
+function removeSidecars(ownerHome: string, report: CredentialsPurgeReport, fail: Fail): void {
+  for (const dir of OPERATOR_SIDECAR_DIRS) {
+    const file = join(ownerHome, dir, BROKER_SIDECAR_FILE);
+    try {
+      const where = below(ownerHome, [dir]);
+      if (where.kind === "none") continue;
+      // The broker writes a file; a directory of that name is the
+      // operator's, like the rest of the dir.
+      const stats = lstatIfThere(join(where.path, BROKER_SIDECAR_FILE));
+      if (stats === null || stats.isDirectory()) continue;
+      if (where.kind === "dir") removeFrom(where, BROKER_SIDECAR_FILE, report.files, fail);
+      else fail(file, throughLink(where));
+    } catch (error) {
+      fail(file, error);
+    }
+  }
+}
+
+/** ssh.ts `writeTaskIdentity`: a task creator's decrypted key, removed after
+ *  task-up unless a crash came first. The `known_hosts` beside them stays. */
+function removeTaskIdentities(dataDir: string, report: CredentialsPurgeReport, fail: Fail): void {
+  removeEverythingIn(dataDir, ["identity", "tasks"], report.dirs, fail);
+}
+
+/**
+ * Each task's `uai` CLI secret, the key its agents' task tokens are signed
+ * with (agent-cli.ts `storeTaskCliSecret`), and its MCP gateway token, which
+ * alone admits a request to the task's gateway routes (mcp-gateway.ts
+ * `ensureTaskGatewayAcl`). Nothing needs either again: every task runtime
+ * was retired before this runs, and a Resume brings both back. The cloud
+ * keeps the CLI secret, the same one across resumes, and sends it with
+ * every task-up, which writes it here again; the first session after one
+ * mints a new gateway token, as after any Stop, which removes the old.
+ */
+function removeTaskSecrets(dataDir: string, report: CredentialsPurgeReport, fail: Fail): void {
+  for (const dir of ["task-secrets", "mcp-gateway"]) removeEverythingIn(dataDir, [dir], report.files, fail);
+}
+
+/** Everything in the directory at `parts` below `root`, a directory Uai
+ *  keeps for itself alone. Uai never makes a link on the way to it, so one
+ *  there is the operator's, and fails the purge whatever is behind it now:
+ *  nothing is removed through it, and nothing there, or nothing at all
+ *  where it leads, proves nothing (an empty mount point, a volume not
+ *  mounted, a link changed back). */
+function removeEverythingIn(root: string, parts: readonly string[], into: string[], fail: Fail): void {
+  const dir = join(root, ...parts);
+  let where: Below;
+  try {
+    where = below(root, parts);
+  } catch (error) {
+    fail(dir, error);
+    return;
+  }
+  if (where.kind === "none") {
+    if (where.via !== undefined) fail(dir, notThereBehindLink(where.via));
+    return;
+  }
+  const entries = listDir(where.path, fail);
+  if (where.kind === "dir") {
+    // Nothing listed proves nothing unless it is still the directory the walk
+    // found: it may have gone, or been swapped, since.
+    if (entries.length === 0) {
+      try {
+        assertUnmoved(where.chain);
+      } catch (error) {
+        fail(dir, error);
+      }
+    }
+    for (const entry of entries) removeFrom(where, entry.name, into, fail);
+  } else if (entries.length > 0) {
+    fail(dir, throughLink(where, `${entries.length} ${entries.length === 1 ? "entry" : "entries"} `));
+  } else {
+    fail(
+      dir,
+      new Error(
+        `empty behind the symbolic link ${where.link} (to ${where.to}), which proves nothing; ` +
+          "replace the link with a directory",
+      ),
+    );
+  }
+}
+
+/** Where this build stages a store write (memory-backed), and where an older
+ *  one staged it on disk. */
+function defaultStagingRoots(): string[] {
+  const memory = memoryBackedDir();
+  return memory === null ? [tmpdir()] : [memory, tmpdir()];
+}
+
+function removeStagedWrites(
+  roots: readonly string[],
+  report: CredentialsPurgeReport,
+  fail: Fail,
+): void {
+  const staged = removeStagedWritesLeftBehind(roots);
+  report.dirs.push(...staged.removed);
+  for (const { path, error } of staged.failed) fail(path, error);
+  for (const path of staged.pending) {
+    fail(path, new Error("a staged credential-store write that may be under way; the purge finishes once it is gone"));
+  }
+}
+
+/**
+ * Every credential row, in one transaction, and then the pages they freed.
+ * `secure_delete` comes first, so each delete zeroes the bytes it frees in
+ * the WAL frames it writes; VACUUM then rebuilds the file without the free
+ * pages earlier deletes left as they were, and the checkpoint moves it all
+ * into the database and truncates the WAL, whose stale frames could still
+ * hold an old copy of any page.
+ */
+function purgeDatabase(
+  accountRowsKept: string[] | null,
+  report: CredentialsPurgeReport,
+  fail: Fail,
+): void {
+  try {
+    withHostSqlite((sqlite) => {
+      if (Number(sqlite.pragma("secure_delete = ON", { simple: true })) !== 1) {
+        throw new Error("SQLite did not turn secure_delete on");
+      }
+    });
+  } catch (error) {
+    fail("host.sqlite secure_delete", error);
+  }
+  try {
+    report.rows = deleteCredentialRows(accountRowsKept);
+    noteProjectEnvAuthorityChange();
+  } catch (error) {
+    fail("host.sqlite credential rows", error);
+  }
+  try {
+    withHostSqlite((sqlite) => {
+      sqlite.exec("VACUUM");
+      const [checkpoint] = sqlite.pragma("wal_checkpoint(TRUNCATE)") as Array<{ busy: number }>;
+      if (checkpoint?.busy !== 0) {
+        throw new Error("a reader kept the WAL from being checkpointed and truncated");
+      }
+    });
+  } catch (error) {
+    fail("host.sqlite freed pages", error);
+  }
+}
+
+function deleteCredentialRows(accountRowsKept: string[] | null): Record<string, number> {
+  const now = Date.now();
+  return getDb().transaction((tx) => {
+    const rows: Record<string, number> = {};
+    const drop = (table: SQLiteTable): void => {
+      rows[getTableName(table)] = tx.delete(table).run().changes;
+    };
+
+    // The owned runner's authority row (project-env-authority.ts) is reset,
+    // not deleted: its every reader takes a missing row for corruption, so a
+    // missing one is made again here. It closes: the gate shut and no
+    // reconciliation attempt left, so it serves nothing and applies no
+    // delivery until a new one begins. Its stream, cursor and legacy
+    // version name no key and hold no value, and only ever move forward, so
+    // they stay. Its `modern_write` fence goes up first, as for every
+    // modern write, so the permanent legacy triggers
+    // (0025_project_env_authority.sql) journal none of the value rows
+    // deleted next, and comes down in this same transaction.
+    tx.insert(schema.hostProjectEnvAuthority)
+      .values({ id: "host", gateOpen: false, modernWrite: true, updatedAt: now })
+      .onConflictDoUpdate({
+        target: schema.hostProjectEnvAuthority.id,
+        set: {
+          gateOpen: false,
+          attemptId: null,
+          attemptLegacyVersion: null,
+          modernWrite: true,
+          updatedAt: now,
+        },
+      })
+      .run();
+    drop(schema.hostProjectEnv);
+    // What an old writer journaled before: each row names a key.
+    drop(schema.hostProjectEnvLegacyJournal);
+    drop(schema.hostProjectEnvRecords);
+    drop(schema.hostProjectEnvProjects);
+    drop(schema.hostProjectEnvDeliveryReceipts);
+    tx.update(schema.hostProjectEnvAuthority)
+      .set({ modernWrite: false })
+      .where(eq(schema.hostProjectEnvAuthority.id, "host"))
+      .run();
+
+    // A task machine's replica (project-env-replica.ts) loses its values;
+    // its records, projects and receipts hold none and stay. Two changes
+    // keep it a replica its readers accept. A staged attempt goes whole: its
+    // values are gone, so it could never commit, and a closing connection
+    // drops one the same way. A live record that said its value is
+    // installed now says the value is not on this machine (`unavailable`,
+    // as for a head not yet fetched), since a reader takes an installed
+    // record without its value for corruption. Its gate closes, as at every
+    // sidecar start, until a reconciliation fetches the values again.
+    drop(schema.hostProjectEnvReplicaStageValues);
+    drop(schema.hostProjectEnvReplicaStageRecords);
+    drop(schema.hostProjectEnvReplicaStageProjects);
+    drop(schema.hostProjectEnvReplicaValues);
+    tx.update(schema.hostProjectEnvReplicaRecords)
+      .set({
+        materialization: "unavailable",
+        materializationReason: "materialization_pending",
+        updatedAt: now,
+      })
+      .where(eq(schema.hostProjectEnvReplicaRecords.materialization, "installed"))
+      .run();
+    tx.update(schema.hostProjectEnvReplicaAuthority)
+      .set({ gateOpen: false, attemptId: null, updatedAt: now })
+      .where(eq(schema.hostProjectEnvReplicaAuthority.id, "replica"))
+      .run();
+
+    if (accountRowsKept !== null) {
+      const accounts = getTableName(schema.engineAccounts);
+      rows[accounts] =
+        accountRowsKept.length === 0
+          ? tx.delete(schema.engineAccounts).run().changes
+          : tx
+              .delete(schema.engineAccounts)
+              .where(notInArray(schema.engineAccounts.id, accountRowsKept))
+              .run().changes;
+    }
+    drop(schema.mcpConnections);
+    drop(schema.githubTokens);
+    drop(schema.githubCredentialGenerations);
+    drop(schema.sshKeys);
+    return rows;
+  });
+}
+
+/** github-tokens.ts: the access tokens it caches, and the exchanges under
+ *  way, which keep nothing when they end. */
+function forgetGithubTokens(fail: Fail): void {
+  try {
+    forgetGithubTokensInMemory();
+  } catch (error) {
+    fail("GitHub tokens in memory", error);
+  }
+}
+
+/**
+ * Nothing is removed through a symbolic link below the owner's home or the
+ * data dir. The roots themselves are taken as configured, links and all.
+ * Below them is where an operator's own layout lives (a dotfiles manager
+ * links `~/.codex` or `~/.local/share`; a data dir moved to another volume
+ * leaves a link behind), and a link there may lead anywhere: a recursive
+ * delete through a linked `task-secrets` would empty whatever it names. So
+ * each directory the purge lists or removes in is walked from its root with
+ * lstat, a component at a time, and what is reached only through a link is
+ * looked for there, never removed. Where the link leads:
+ * - to something the purge would remove: the purge fails, naming it, the
+ *   link and where it leads, for the operator to remove it there (an
+ *   account row behind one stays);
+ * - to nothing the purge would remove: there is nothing to do, and no
+ *   failure. The link and what it leads to are the operator's own, and
+ *   none of it is Uai's. Failing would keep the runner pending, running no
+ *   task, until the operator undid their own layout (a symlinked
+ *   `~/.local/share` holding no OpenCode account of Uai's, say) for
+ *   nothing the purge has to remove;
+ * - to nothing at all: the purge fails, naming it and its target, as for a
+ *   `.env.local` link to nothing. What is behind it cannot be seen, it may
+ *   come back (a volume mounted again) holding what the purge removes, and
+ *   once activation is done nothing would run the purge again. The
+ *   operator removes the link or brings back what it names.
+ * A component that is something other than a directory or a link has
+ * nothing behind it.
+ *
+ * A walk with lstat does not hold on to what it walked. Node has no openat
+ * or unlinkat, and reads a directory only by its path, so a removal names
+ * its path from the root again and the kernel resolves it anew. Just before
+ * each removal, then, every component is checked again, the same directory
+ * (device and inode) and still not a link, and a change fails the purge.
+ * What that leaves open is the instant between the check and rmSync's own
+ * lookup, and, inside what rmSync removes, its own walk (an lstat, then a
+ * readdir). Only a process writing these directories while the purge runs
+ * could swap a link in there, and every task runtime was retired before.
+ */
+type Below = NoDir | ProvenDir | LinkedDir;
+
+/** Not there: a component missing, or not a directory. `via` is the first
+ *  link the walk came through before it, if any: behind one, absence proves
+ *  nothing. */
+interface NoDir {
+  kind: "none";
+  via?: { link: string; to: string };
+}
+
+/** Every component a directory, none a link; `chain` holds each as the
+ *  walk found it. */
+interface ProvenDir {
+  kind: "dir";
+  path: string;
+  chain: readonly Component[];
+}
+
+/** Reached only through `link`, the first link on the way (as named below
+ *  the root), which leads to `to`; `path` is the directory itself. */
+interface LinkedDir {
+  kind: "linked";
+  path: string;
+  link: string;
+  to: string;
+}
+
+interface Component {
+  path: string;
+  dev: bigint;
+  ino: bigint;
+}
+
+/** The directory at `parts` below `root`, walked as above; "none" when a
+ *  component is missing or is not a directory. Throws when the root is not
+ *  a directory that is there (nothing below it can be seen), or a link on
+ *  the way leads to nothing. */
+function below(root: string, parts: readonly string[]): Below {
+  const real = realpathIfThere(root);
+  if (real === null || !statSync(real).isDirectory()) {
+    throw new Error(`${root} is not a directory that is there; nothing in it can be seen`);
+  }
+  const chain: Component[] = [];
+  let at = root;
+  let crossed: { link: string; to: string } | undefined;
+  const none = (): NoDir => (crossed === undefined ? { kind: "none" } : { kind: "none", via: crossed });
+  for (const part of parts) {
+    const path = join(at, part);
+    const stats = lstatIfThere(path);
+    if (stats === null) return none();
+    if (stats.isSymbolicLink()) {
+      const to = realpathIfThere(path);
+      if (to === null) {
+        throw new Error(
+          `the symbolic link ${path} (to ${readlinkSync(path)}) leads to nothing; remove it, or bring back what it names`,
+        );
+      }
+      crossed ??= { link: path, to };
+      // A real path names no link: the walk goes on from where this one leads.
+      if (!lstatSync(to).isDirectory()) return none();
+      at = to;
+      continue;
+    }
+    if (!stats.isDirectory()) return none();
+    if (crossed === undefined) chain.push({ path, dev: stats.dev, ino: stats.ino });
+    at = path;
+  }
+  return crossed === undefined ? { kind: "dir", path: at, chain } : { kind: "linked", path: at, ...crossed };
+}
+
+/** Throws unless each component is still the directory the walk found. */
+function assertUnmoved(chain: readonly Component[]): void {
+  for (const { path, dev, ino } of chain) {
+    const stats = lstatSync(path, { bigint: true });
+    if (!stats.isDirectory() || stats.dev !== dev || stats.ino !== ino) {
+      throw new Error(`${path} changed while the purge ran; nothing below it is removed`);
+    }
+  }
+}
+
+/** Removes `name`, and all under it, from a directory the walk proved,
+ *  noted in `into` when it was there. Never a link (removing it would leave
+ *  what the runner wrote through it), nor what holds one (assertNoAliases). */
+function removeFrom(where: ProvenDir, name: string, into: string[], fail: Fail): void {
+  const path = join(where.path, name);
+  try {
+    const stats = lstatIfThere(path);
+    if (stats === null) return;
+    if (stats.isSymbolicLink()) {
+      throw new Error(
+        `a symbolic link (to ${readlinkSync(path)}) where Uai writes; neither it nor what it leads to is removed`,
+      );
+    }
+    assertNoAliases(path);
+    assertUnmoved(where.chain);
+    rmSync(path, { recursive: true, force: true });
+  } catch (error) {
+    fail(path, error);
+    return;
+  }
+  into.push(path);
+}
+
+function throughLink(where: LinkedDir, what = ""): Error {
+  return new Error(`${what}behind the symbolic link ${where.link} (to ${where.to}); nothing is removed through a link`);
+}
+
+/** Something the purge must find gone, not there behind a link: it may come
+ *  back there (a volume mounted again, the link changed back). */
+function notThereBehindLink(via: { link: string; to: string }): Error {
+  return new Error(
+    `not there behind the symbolic link ${via.link} (to ${via.to}), which proves nothing; ` +
+      "bring back what it names, or replace the link with a directory",
+  );
+}
+
+function lstatIfThere(path: string): BigIntStats | null {
+  try {
+    return lstatSync(path, { bigint: true });
+  } catch (error) {
+    if (isMissing(error)) return null;
+    throw error;
+  }
+}
+
+function realpathIfThere(path: string): string | null {
+  try {
+    return realpathSync(path);
+  } catch (error) {
+    if (isMissing(error)) return null;
+    throw error;
+  }
+}
+
+/** A directory's entries; none when it does not exist. One that cannot be
+ *  read is a failure: what it holds is unknown. */
+function listDir(dir: string, fail: Fail): Dirent[] {
+  try {
+    return readdirSync(dir, { withFileTypes: true });
+  } catch (error) {
+    if (!isMissing(error)) fail(dir, error);
+    return [];
+  }
+}
+
+function isMissing(error: unknown): boolean {
+  const code = (error as NodeJS.ErrnoException | null)?.code;
+  return code === "ENOENT" || code === "ENOTDIR";
+}