getbotons 0.0.0-stage → 0.1.0

package/payload/server/src/index.ts

@@ -0,0 +1,139 @@
+import './env-init.ts';
+import { log, setLogLevel } from './log.ts';
+import { type App, createApp } from './app.ts';
+import { VERSION } from './api.ts';
+import { type Config, ConfigError, DataDirError, formatDuration, loadConfig } from './config.ts';
+import { NameUpgradeError, upgradeDataFolder } from './legacy-upgrade.ts';
+import { DataDirInUseError } from './lock.ts';
+import { SchemaError } from './schema.ts';
+import { approveCommand } from './setup.ts';
+
+// Node's own warnings as JSON log lines too, so `journalctl ... | jq .` parses every line.
+process.removeAllListeners('warning');
+process.on('warning', (w) => log.warn(w.message, { warning: w.name, code: (w as NodeJS.ErrnoException).code }));
+
+let app: App | null = null;
+// The process is in an unknown state: stop the agent processes and let systemd restart a clean server.
+process.on('uncaughtException', (err, origin) => {
+  log.error(`fatal ${origin}: stopping running turns and exiting`, { origin, err });
+  try {
+    app?.engine.stopAll();
+  } catch (stopErr) {
+    log.error('could not stop running turns', { err: stopErr });
+  }
+  process.exit(1);
+});
+// Log and keep serving (instead of Node's default: an uncaught exception).
+process.on('unhandledRejection', (reason) => {
+  log.error('unhandled promise rejection', { err: reason });
+});
+
+function config(): Config {
+  try {
+    return loadConfig();
+  } catch (err) {
+    if (err instanceof DataDirError) {
+      // EX_CONFIG: restarting cannot fix it (systemd: RestartPreventExitStatus=78).
+      log.error(`Botons cannot start: ${err.message}`);
+      process.exit(78);
+    }
+    if (!(err instanceof ConfigError)) throw err;
+    // EX_CONFIG: restarting cannot fix it, so systemd does not retry (RestartPreventExitStatus=78).
+    log.error(`Botons cannot start: fix these settings (environment variables) first: ${err.errors.join('; ')}`, { errors: err.errors });
+    process.exit(78);
+  }
+}
+// A data folder or database still under a deprecated name moves to its current one first (legacy-upgrade.ts).
+try {
+  for (const line of upgradeDataFolder().lines) log.info(line);
+} catch (err) {
+  if (err instanceof DataDirInUseError) {
+    // Not EX_CONFIG: the folder frees up when the other server stops, so a retry can succeed.
+    log.error(err.message);
+    process.exit(1);
+  }
+  // A setting problem is reported by config() below; anything else leaves the data where it is, still in use.
+  if (!(err instanceof ConfigError)) log.warn(`the data folder keeps its deprecated name for now: ${(err as Error).message}`, { err: err instanceof NameUpgradeError ? undefined : err });
+}
+const cfg = config();
+setLogLevel(cfg.logLevel);
+for (const n of cfg.envNotices) {
+  if (n.conflict) log.warn('a setting is set under both its name and a deprecated name, to different values: its name is used', { setting: n.name, deprecated: n.old });
+  else log.warn('a setting uses a deprecated name, which works for this release only', { setting: n.name, deprecated: n.old });
+}
+
+async function open(): Promise<App> {
+  try {
+    return createApp(cfg, undefined, { releaseChecks: true });
+  } catch (err) {
+    if (err instanceof DataDirInUseError) {
+      // Not EX_CONFIG: the folder frees up when the other server stops, so a retry can succeed.
+      log.error(err.message);
+      process.exit(1);
+    }
+    if (!(err instanceof SchemaError)) throw err;
+    // EX_CONFIG: restarting cannot fix it (systemd: RestartPreventExitStatus=78).
+    log.error(`Botons cannot open ${cfg.dbPath}: ${err.message}`);
+    process.exit(78);
+  }
+}
+app = await open();
+const running = app;
+
+try {
+  await running.listen();
+} catch (err) {
+  log.error(`Could not start Botons on port ${cfg.port} (${cfg.hosts.join(', ')}): ${(err as Error).message}`, { err });
+  process.exit(1);
+}
+
+// SIGHUP too: its default (the terminal running `npm start` closed) would skip the drain and leave agent CLIs running.
+let signals = 0;
+for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP'] as const) {
+  process.on(sig, () => {
+    signals++;
+    if (signals === 2) {
+      log.info(`shutdown: ${sig} again: stopping running turns now`);
+      running.engine.interruptAll();
+      return;
+    }
+    if (signals > 2) process.exit(1);
+    log.info(`shutdown: ${sig}: taking no new work; giving running turns up to ${formatDuration(cfg.drainMs)} to finish (${sig} again stops them now)`);
+    running.close({ drainMs: cfg.drainMs }).then(
+      ({ interrupted }) => {
+        log.info(
+          interrupted
+            ? `shutdown: stopped ${interrupted} turn${interrupted === 1 ? '' : 's'} that had not finished; the next start answers cut-off chat messages again (with a note) and marks cut-off routine runs as interrupted`
+            : 'shutdown: done',
+          { interrupted },
+        );
+        process.exit(0);
+      },
+      (err) => {
+        log.error('shutdown failed', { err });
+        process.exit(1);
+      },
+    );
+  });
+}
+
+const providers = await running.providers.infos();
+log.info(`Botons ${VERSION}${cfg.build ? ` (${cfg.build.slice(0, 12)})` : ''} is running at ${cfg.urls.join(', ')}`, {
+  version: VERSION,
+  build: cfg.build,
+  urls: cfg.urls,
+  home: cfg.home,
+  logLevel: cfg.logLevel,
+  providers: providers.map((p) => ({ provider: p.id, available: p.available, version: p.version ?? undefined, loggedIn: p.loggedIn ?? undefined })),
+});
+for (const p of providers) {
+  if (p.available) continue;
+  // A CLI that is not installed may simply be unused.
+  (p.installed ? log.warn : log.info)(`${p.label} can't run turns: ${p.reason}`, { provider: p.id, installed: p.installed, loggedIn: p.loggedIn });
+}
+if (!cfg.authEnabled) log.warn('auth is OFF (BOTONS_AUTH=off): anyone who can reach this server can use it, Botons included.');
+else if (!running.auth.claimed()) {
+  log.info(`No owner yet: open ${cfg.publicUrl}, which shows a code, and claim this server by approving it with \`${approveCommand(cfg)}\` on this machine (or with one click from your own Tailscale device).`);
+} else if (!running.auth.devices(null).length) {
+  log.info(`No device is paired. Open ${cfg.publicUrl}, which shows a code, and approve it here with \`${approveCommand(cfg)}\`.`);
+}

package/payload/server/src/install-type.ts

@@ -0,0 +1,11 @@
+import { existsSync } from 'node:fs';
+import { dirname, basename, resolve, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { installCommand, type InstallType } from '../../shared/install-commands.ts';
+export function installType(container = false, app = resolve(dirname(fileURLToPath(import.meta.url)), '../..')): InstallType {
+  if (container) return 'docker';
+  return basename(dirname(app)) === 'releases' && existsSync(join(dirname(dirname(app)), 'installer.json')) ? 'managed' : 'service';
+}
+export function serverCommand(action: Parameters<typeof installCommand>[1], args = '', container = process.env.BOTONS_CONTAINER === '1'): string {
+  return installCommand(installType(container), action, args);
+}

package/payload/server/src/instructions.ts

@@ -0,0 +1,204 @@
+import { closeSync, constants, fstatSync, openSync, readlinkSync, readSync, symlinkSync, unlinkSync, writeSync } from 'node:fs';
+import { readdir } from 'node:fs/promises';
+import { join, sep } from 'node:path';
+import { heldLookups, heldPath, holdBeneath, holdDir, LinkInTheWay, NoHeldLookups, under, type HeldDir } from './held-dir.ts';
+import { log } from './log.ts';
+
+// What agent CLIs load as standing instructions from a workspace: a sandboxed (webhook) turn must not
+// leave any behind, or every later turn of the Boton, Full computer ones included, would follow them.
+export const INSTRUCTION_FILES = ['CLAUDE.md', 'CLAUDE.local.md', 'AGENTS.md', 'AGENTS.override.md'];
+
+/** The paths a sandboxed turn in `cwd` may not write (files or folders; they need not exist). */
+export function instructionPaths(cwd: string): string[] {
+  return [...INSTRUCTION_FILES, '.codex', '.agents'].map((name) => join(cwd, name));
+}
+
+const WALK_MAX_DEPTH = 8;
+const WALK_MAX_ENTRIES = 20_000;
+const SNAPSHOT_MAX_BYTES = 1024 * 1024;
+const SKIP_DIRS = new Set(['.git', 'node_modules']);
+
+type Entry = { kind: 'file'; data: Buffer | null; size: number; mtimeMs: number } | { kind: 'link'; target: string };
+
+/** Tests only: called right before each instruction file is read, by its relative path (to change things there). */
+export interface SnapshotHooks {
+  beforeRead?: (rel: string) => void;
+}
+
+/**
+ * The entry `name` in the open folder `dir` (held-dir.ts), never through a link: a link is noted as a link, and a
+ * file is read from the descriptor opened, at most SNAPSHOT_MAX_BYTES of it. The turn can swap anything in its
+ * workspace meanwhile; what is read is still what was there, in the workspace.
+ */
+function entryIn(dir: HeldDir, name: string): Entry | null {
+  const at = under(dir, name);
+  let fd: number;
+  try {
+    // Non-blocking, so a named pipe put there doesn't hang the open; it is not a file, so it is left alone.
+    fd = openSync(at, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== 'ELOOP') return null;
+    try {
+      return { kind: 'link', target: readlinkSync(at) };
+    } catch {
+      return null;
+    }
+  }
+  try {
+    const st = fstatSync(fd);
+    if (!st.isFile()) return null;
+    if (st.size > SNAPSHOT_MAX_BYTES) return { kind: 'file', size: st.size, mtimeMs: st.mtimeMs, data: null };
+    const buf = Buffer.alloc(SNAPSHOT_MAX_BYTES + 1);
+    let n = 0;
+    for (let got = 1; got > 0 && n < buf.length; n += got) got = readSync(fd, buf, n, buf.length - n, null);
+    // Grown past the limit since its size was read: too big to keep a copy of.
+    if (n > SNAPSHOT_MAX_BYTES) return { kind: 'file', size: n, mtimeMs: st.mtimeMs, data: null };
+    return { kind: 'file', size: n, mtimeMs: st.mtimeMs, data: Buffer.from(buf.subarray(0, n)) };
+  } catch {
+    return null;
+  } finally {
+    closeSync(fd);
+  }
+}
+
+function same(a: Entry, b: Entry): boolean {
+  if (a.kind === 'link' || b.kind === 'link') return a.kind === 'link' && b.kind === 'link' && a.target === b.target;
+  if (a.size !== b.size) return false;
+  // Too big to keep a copy of: unchanged if it wasn't written.
+  return a.data && b.data ? a.data.equals(b.data) : a.mtimeMs === b.mtimeMs;
+}
+
+/**
+ * Every instruction file under `root` (by relative path), within the walk's limits. Each folder is opened from the one
+ * above it and held open while it is listed and its files read, never through a link (held-dir.ts): the server reads
+ * here outside the turn's sandbox, so a folder the turn swapped for a link to one of the owner's is not followed.
+ */
+async function findInstructionFiles(root: string, hooks: SnapshotHooks): Promise<Map<string, Entry>> {
+  const found = new Map<string, Entry>();
+  let top: HeldDir;
+  try {
+    top = holdDir(root);
+  } catch {
+    return found;
+  }
+  let seen = 0;
+  const walk = async (dir: HeldDir, rel: string[], depth: number) => {
+    let names: import('node:fs').Dirent[];
+    try {
+      names = await readdir(heldPath(dir), { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const d of names) {
+      if (++seen > WALK_MAX_ENTRIES) return;
+      const path = [...rel, d.name];
+      if (INSTRUCTION_FILES.includes(d.name) && (d.isFile() || d.isSymbolicLink())) {
+        hooks.beforeRead?.(join(...path));
+        const e = entryIn(dir, d.name);
+        if (e) found.set(join(...path), e);
+      } else if (d.isDirectory() && depth < WALK_MAX_DEPTH && !SKIP_DIRS.has(d.name)) {
+        let sub: HeldDir;
+        try {
+          sub = holdBeneath(dir, [d.name]);
+        } catch {
+          continue;
+        }
+        try {
+          await walk(sub, path, depth + 1);
+        } finally {
+          closeSync(sub.fd);
+        }
+      }
+    }
+  };
+  try {
+    await walk(top, [], 0);
+  } finally {
+    closeSync(top.fd);
+  }
+  return found;
+}
+
+/**
+ * Puts `e` (or nothing) at `rel`, by folders held open from the workspace down (held-dir.ts): the server does this
+ * outside the turn's sandbox, so a folder on the way the turn replaced with a link is not followed but refused.
+ */
+function putAt(top: HeldDir, rel: string, e: Entry | undefined): void {
+  const parts = rel.split(sep);
+  const name = parts.pop()!;
+  let dir: HeldDir;
+  try {
+    dir = holdBeneath(top, parts, e?.kind === 'file');
+  } catch (err) {
+    // Nothing to take away under a folder that isn't there.
+    if (!e && (err as NodeJS.ErrnoException).code === 'ENOENT') return;
+    throw err;
+  }
+  try {
+    const at = under(dir, name);
+    try {
+      unlinkSync(at);
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
+    }
+    if (e?.kind === 'link') symlinkSync(e.target, at);
+    else if (e?.kind === 'file' && e.data) {
+      // A new file of its own: never through a link put there meanwhile.
+      const fd = openSync(at, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o666);
+      try {
+        for (let n = 0; n < e.data.length; ) n += writeSync(fd, e.data, n, e.data.length - n);
+      } finally {
+        closeSync(fd);
+      }
+    }
+  } finally {
+    if (dir !== top) closeSync(dir.fd);
+  }
+}
+
+/**
+ * Note the workspace's instruction files before a sandboxed turn. The function it returns puts back
+ * what the turn created, changed or deleted, and returns their relative paths.
+ */
+export async function snapshotInstructions(root: string, hooks: SnapshotHooks = {}): Promise<() => Promise<string[]>> {
+  // Without lookups in an open folder (not Linux) nothing is read or put back by path: a swap would redirect it.
+  if (!heldLookups) throw new NoHeldLookups();
+  const before = await findInstructionFiles(root, hooks);
+  return async () => {
+    const after = await findInstructionFiles(root, {});
+    const undone: string[] = [];
+    let top: HeldDir;
+    try {
+      top = holdDir(root);
+    } catch (err) {
+      log.warn('could not put back the instruction files a sandboxed turn changed: its workspace could not be opened', { root, err });
+      return undone;
+    }
+    const put = (rel: string, e: Entry | undefined) => {
+      const path = join(root, rel);
+      try {
+        if (e?.kind === 'file' && !e.data) {
+          // What the turn left there still goes.
+          putAt(top, rel, undefined);
+          log.warn('could not put back an instruction file a sandboxed turn changed: it was too big to keep a copy of', { path });
+          return;
+        }
+        putAt(top, rel, e);
+        undone.push(rel);
+      } catch (err) {
+        if (err instanceof LinkInTheWay) log.warn('did not put back an instruction file a sandboxed turn changed: a folder on its way is now a link, which is not followed', { path });
+        else log.warn('could not put back an instruction file a sandboxed turn changed', { path, err });
+      }
+    };
+    try {
+      for (const [rel, e] of after) {
+        const was = before.get(rel);
+        if (!was || !same(was, e)) put(rel, was);
+      }
+      for (const [rel, was] of before) if (!after.has(rel)) put(rel, was);
+    } finally {
+      closeSync(top.fd);
+    }
+    return undone;
+  };
+}

package/payload/server/src/isolation.ts

@@ -0,0 +1,234 @@
+import { existsSync, lstatSync, mkdirSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { CONFIG_DIRS, DATA_DIRS } from '../../shared/legacy-names.mjs';
+import { delimiter, join, resolve, sep } from 'node:path';
+
+/** Botons run as the server's user, so file modes don't keep these out of a Workspace Boton; this list does. */
+const HOME_SECRETS = [
+  '.ssh',
+  '.gnupg',
+  '.password-store',
+  '.local/share/keyrings',
+  '.pki',
+  '.local/share/pki',
+  '.config/op',
+  '.config/1Password',
+  '.config/Bitwarden',
+  '.aws',
+  '.azure',
+  '.kube',
+  '.docker',
+  '.netrc',
+  '.git-credentials',
+  '.config/gh',
+  '.config/hub',
+  '.config/glab-cli',
+  '.config/gcloud',
+  '.config/doctl',
+  '.config/rclone',
+  '.terraform.d/credentials.tfrc.json',
+  '.pulumi/credentials.json',
+  '.fly',
+  '.vault-token',
+  '.npmrc',
+  '.pypirc',
+  '.gem/credentials',
+  '.cargo/credentials',
+  '.cargo/credentials.toml',
+  '.claude.json',
+  '.config/anthropic',
+  '.config/github-copilot',
+  '.gemini',
+  '.pi',
+  '.hermes',
+  '.config/opencode',
+  '.local/share/opencode',
+  '.t3/userdata',
+  '.config/Slack',
+  '.config/discord',
+  '.config/Signal',
+  '.mozilla',
+  '.librewolf',
+  '.zen',
+  '.floorp',
+  '.waterfox',
+  '.config/google-chrome',
+  '.config/google-chrome-beta',
+  '.config/google-chrome-unstable',
+  '.config/chromium',
+  '.config/BraveSoftware',
+  '.config/vivaldi',
+  '.config/vivaldi-snapshot',
+  '.config/microsoft-edge',
+  '.config/microsoft-edge-beta',
+  '.config/microsoft-edge-dev',
+  '.config/opera',
+  '.config/opera-beta',
+  '.config/thorium',
+  '.bash_history',
+  '.zsh_history',
+  '.histfile',
+  '.local/share/fish/fish_history',
+  '.local/share/atuin',
+  '.python_history',
+  '.node_repl_history',
+  '.psql_history',
+  '.mysql_history',
+  '.sqlite_history',
+  '.config/botons',
+  // Settings folders under deprecated names stay on disk after the upgrade, and may hold secrets.
+  ...CONFIG_DIRS.map((d) => `.config/${d}`),
+];
+
+/** BOTONS_PRIVATE_PATHS: separated like PATH, each absolute, "~/…", or relative to the home folder. */
+export function parsePrivatePaths(value: string | undefined, userHome: string = homedir()): string[] {
+  return (value ?? '')
+    .split(delimiter)
+    .map((p) => p.trim())
+    .filter(Boolean)
+    .map((p) => resolve(userHome, p.replace(/^~(?=\/|$)/, '.')));
+}
+
+export type AgentCli = 'claude' | 'codex';
+
+// What the running CLI's sandboxed commands still need in its own folder; the rest of it, and all of the other CLI's, is private.
+const CLAUDE_KEEP = new Set(['projects', 'shell-snapshots', 'session-env']);
+const CODEX_KEEP = new Set(['tmp', 'shell_snapshots']);
+
+/** Claude Code's folder for a working directory's sessions, under ~/.claude/projects. */
+export function claudeProjectDir(cwd: string): string {
+  return resolve(cwd).replace(/[^a-zA-Z0-9]/g, '-');
+}
+
+const isLink = (p: string) => {
+  try {
+    return lstatSync(p).isSymbolicLink();
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * The data folder's private storage that is made only when first needed (the first backup, the first file deleted to
+ * the trash, ...). A Workspace turn's CLI takes its private paths once, as it starts, so a folder made later would not
+ * be on them: each is made before the list is taken, empty and private, and is on every list from then on.
+ */
+const RESERVED_HOME_DIRS: readonly string[] = ['backups', 'trash', 'run', 'browser', 'api-sessions', 'templates', 'skill-packages'];
+
+/**
+ * Makes each of RESERVED_HOME_DIRS that is missing, and returns where each really is (a folder of the owner's linked
+ * there, say, is listed by the link and by its folder). Throws when one can't be made or isn't a folder: the turn
+ * then doesn't start, rather than start without it on its list.
+ */
+function reserveHomeDirs(botonsHome: string): string[] {
+  if (!existsSync(botonsHome)) return [];
+  const out: string[] = [];
+  for (const name of RESERVED_HOME_DIRS) {
+    const p = join(botonsHome, name);
+    try {
+      mkdirSync(p, { mode: 0o700 });
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== 'EEXIST') throw new Error(`Botons could not make ${p}, which a Workspace turn must have on its private paths before it starts (${(err as NodeJS.ErrnoException).code ?? (err as Error).message})`);
+    }
+    let real: string;
+    try {
+      real = realpathSync(p);
+      if (!statSync(real).isDirectory()) throw new Error('not a folder');
+    } catch {
+      throw new Error(`${p} is not a folder, so a Workspace turn can't have it on its private paths; move it aside and Botons makes it again`);
+    }
+    if (real !== p) out.push(real);
+  }
+  return out;
+}
+
+/**
+ * Paths a Workspace Boton must not read: home secrets, BOTONS_PRIVATE_PATHS (`extra`), the CLIs' logins and other
+ * sessions, everything in BOTONS_HOME (RESERVED_HOME_DIRS made first) and other workspaces. Only paths that exist, and
+ * never one holding the Boton's own workspace or a shared folder.
+ */
+export function privatePaths(input: {
+  workspace: string;
+  cli: AgentCli | null;
+  botonsHome: string;
+  workspacesDir: string;
+  userHome?: string;
+  env?: NodeJS.ProcessEnv;
+  extra?: string[];
+  shared?: string[];
+}): string[] {
+  const home = input.userHome ?? homedir();
+  const env = input.env ?? process.env;
+  const own = resolve(input.workspace);
+  const found = new Set<string>();
+  const entries = (dir: string) => {
+    try {
+      return readdirSync(dir);
+    } catch {
+      return [];
+    }
+  };
+
+  for (const rel of HOME_SECRETS) found.add(join(home, rel));
+  for (const p of input.extra ?? []) found.add(resolve(p));
+
+  for (const kind of ['codex', 'claude']) {
+    const personal = join(home, `.${kind}`);
+    if (resolve(env[kind === 'codex' ? 'CODEX_HOME' : 'CLAUDE_CONFIG_DIR'] || personal) !== personal) found.add(personal);
+  }
+  const claudeDir = resolve(env.CLAUDE_CONFIG_DIR || join(home, '.claude'));
+  if (input.cli === 'claude') {
+    for (const e of entries(claudeDir)) if (!CLAUDE_KEEP.has(e)) found.add(join(claudeDir, e));
+    const ownProject = claudeProjectDir(own);
+    for (const e of entries(join(claudeDir, 'projects'))) if (e !== ownProject) found.add(join(claudeDir, 'projects', e));
+  } else found.add(claudeDir);
+
+  const codexDir = resolve(env.CODEX_HOME || join(home, '.codex'));
+  if (input.cli === 'codex') {
+    for (const e of entries(codexDir)) if (!CODEX_KEEP.has(e)) found.add(join(codexDir, e));
+  } else found.add(codexDir);
+
+  const botonsHome = resolve(input.botonsHome);
+  const workspacesDir = resolve(input.workspacesDir);
+  for (const p of reserveHomeDirs(botonsHome)) found.add(p);
+  for (const e of entries(botonsHome)) {
+    if (e !== 'cli') found.add(join(botonsHome, e));
+    else for (const kind of entries(join(botonsHome, e))) {
+      const dir = join(botonsHome, e, kind);
+      if (dir !== codexDir && dir !== claudeDir) found.add(dir);
+    }
+  }
+  for (const e of entries(workspacesDir)) found.add(join(workspacesDir, e));
+
+  const open = [own, ...(input.shared ?? []).map((p) => resolve(p))];
+  const out = [...found].filter((p) => !open.some((o) => p === o || o.startsWith(p + sep)) && existsSync(p));
+  // The data folder by its deprecated default names too (links to it the upgrade leaves), so a path through a
+  // link names each private path as well.
+  const real = (p: string) => {
+    try {
+      return realpathSync(p);
+    } catch {
+      return null;
+    }
+  };
+  const aliases = DATA_DIRS
+    .map((n) => join(home, n))
+    .filter((a) => a !== botonsHome && isLink(a) && real(a) !== null && real(a) === real(botonsHome));
+  for (const a of aliases) for (const p of [...out]) if (p.startsWith(botonsHome + sep)) out.push(a + p.slice(botonsHome.length));
+  return out;
+}
+
+/**
+ * Codex masks each non-runtime entry in its config directory separately. Bubblewrap cannot mount a
+ * file mask onto a symlink. Inspect metadata only: do not read instructions, skills or credentials,
+ * resolve their targets into a different policy, or replace anything in the owner's configuration.
+ */
+export function codexConfigSymlinks(env: NodeJS.ProcessEnv = process.env, userHome = homedir()): string[] {
+  const dir = resolve(env.CODEX_HOME || join(userHome, '.codex'));
+  if (isLink(dir)) return ['CODEX_HOME'];
+  try {
+    return readdirSync(dir).filter((name) => !CODEX_KEEP.has(name) && isLink(join(dir, name))).map((name) => `CODEX_HOME/${name}`).sort();
+  } catch {
+    return [];
+  }
+}