@zgeoff/atc 3.3.1 → 3.4.1

package/src/agents/update-claude-project-trust.ts

@@ -3,6 +3,7 @@ import { readFile, realpath, rename, rm, stat, writeFile } from 'node:fs/promise
 import { dirname, join } from 'node:path';
 import { isRecord } from '../shared/report';
 import { withClaudeConfigLock } from './with-claude-config-lock';
+import type { ClaudeConfigLockOptions } from './with-claude-config-lock';
 
 /**
  * Accepts the Claude CLI's folder trust for one exact directory in its
@@ -15,30 +16,36 @@ import { withClaudeConfigLock } from './with-claude-config-lock';
  * Resolves to a function that takes the trust back, for a launch that
  * fails before the CLI starts: it puts back the entry as it was, unless
  * something has changed the entry since, which leaves it as it stands.
+ * The lock options apply to both the trust and its taking back.
  */
 export async function updateClaudeProjectTrust(
   configPath: string,
   root: string,
+  lockOptions: ClaudeConfigLockOptions = {},
 ): Promise<() => Promise<void>> {
-  const previous = await withClaudeConfigLock(configPath, async () => {
-    const config = await loadClaudeConfig(configPath);
+  const previous = await withClaudeConfigLock(
+    configPath,
+    async () => {
+      const config = await loadClaudeConfig(configPath);
 
-    const projects = isRecord(config['projects']) ? config['projects'] : {};
-    const entry = projects[root];
+      const projects = isRecord(config['projects']) ? config['projects'] : {};
+      const entry = projects[root];
 
-    if (isRecord(entry) && entry['hasTrustDialogAccepted'] === true) {
-      return null;
-    }
+      if (isRecord(entry) && entry['hasTrustDialogAccepted'] === true) {
+        return null;
+      }
 
-    const base = isRecord(entry) ? entry : {};
+      const base = isRecord(entry) ? entry : {};
 
-    await writeClaudeConfig(configPath, {
-      ...config,
-      projects: { ...projects, [root]: { ...base, hasTrustDialogAccepted: true } },
-    });
+      await writeClaudeConfig(configPath, {
+        ...config,
+        projects: { ...projects, [root]: { ...base, hasTrustDialogAccepted: true } },
+      });
 
-    return { entry: isRecord(entry) ? entry : null };
-  });
+      return { entry: isRecord(entry) ? entry : null };
+    },
+    lockOptions,
+  );
 
   if (previous === null) {
     return () => Promise.resolve();
@@ -50,22 +57,26 @@ export async function updateClaudeProjectTrust(
   });
 
   return () =>
-    withClaudeConfigLock(configPath, async () => {
-      const config = await loadClaudeConfig(configPath);
-
-      const projects = isRecord(config['projects']) ? config['projects'] : {};
-
-      if (JSON.stringify(projects[root]) !== written) {
-        return;
-      }
-
-      const { [root]: _trusted, ...others } = projects;
-
-      await writeClaudeConfig(configPath, {
-        ...config,
-        projects: previous.entry === null ? others : { ...others, [root]: previous.entry },
-      });
-    });
+    withClaudeConfigLock(
+      configPath,
+      async () => {
+        const config = await loadClaudeConfig(configPath);
+
+        const projects = isRecord(config['projects']) ? config['projects'] : {};
+
+        if (JSON.stringify(projects[root]) !== written) {
+          return;
+        }
+
+        const { [root]: _trusted, ...others } = projects;
+
+        await writeClaudeConfig(configPath, {
+          ...config,
+          projects: previous.entry === null ? others : { ...others, [root]: previous.entry },
+        });
+      },
+      lockOptions,
+    );
 }
 
 // The config as the CLI last wrote it; a missing file is an empty config,

package/src/agents/with-claude-config-lock.ts

@@ -1,5 +1,7 @@
 import { mkdir, rmdir, stat, utimes } from 'node:fs/promises';
 import { dirname } from 'node:path';
+import type { Clock } from '../shared/system-clock';
+import { systemClock } from '../shared/system-clock';
 
 // A lock older than this belongs to a holder that died: the Claude CLI's
 // lock library refreshes a held lock's age well inside it.
@@ -12,6 +14,16 @@ const REFRESH_MS = 1000;
 const WAIT_MS = 5000;
 const RETRY_MS = 50;
 
+/**
+ * Tuning a caller may pass: the clock that times and stamps each refresh of
+ * a held lock's age, and a callback run each time the lock is found held by
+ * someone else.
+ */
+export interface ClaudeConfigLockOptions {
+  readonly clock?: Clock;
+  readonly onBusy?: () => void;
+}
+
 /**
  * Runs the callback while holding the lock the Claude CLI takes before it
  * writes its global config: a directory beside the file named for it with
@@ -25,6 +37,7 @@ const RETRY_MS = 50;
 export async function withClaudeConfigLock<T>(
   configPath: string,
   run: () => Promise<T>,
+  options: ClaudeConfigLockOptions = {},
 ): Promise<T> {
   const lockPath = `${configPath}.lock`;
   const deadline = Date.now() + WAIT_MS;
@@ -34,6 +47,8 @@ export async function withClaudeConfigLock<T>(
   let held = await tryCreateLockDir(lockPath);
 
   while (held === null) {
+    options.onBusy?.();
+
     if (Date.now() > deadline) {
       throw new Error(`timed out waiting for the Claude config lock ${lockPath}`);
     }
@@ -43,21 +58,27 @@ export async function withClaudeConfigLock<T>(
     held = await tryCreateLockDir(lockPath);
   }
 
+  const clock = options.clock ?? systemClock;
   let owned: OwnedLock = held;
   let refreshing = Promise.resolve();
 
-  const timer = setInterval(() => {
-    refreshing = (async () => {
-      const refreshed = await refreshOwnedLock(lockPath, owned);
+  const scheduleRefresh = (): (() => void) =>
+    clock.schedule(() => {
+      refreshing = (async () => {
+        const refreshed = await refreshOwnedLock(lockPath, owned, clock.now());
+
+        owned = refreshed ?? owned;
+      })();
+
+      stopRefreshing = scheduleRefresh();
+    }, REFRESH_MS);
 
-      owned = refreshed ?? owned;
-    })();
-  }, REFRESH_MS);
+  let stopRefreshing = scheduleRefresh();
 
   try {
     return await run();
   } finally {
-    clearInterval(timer);
+    stopRefreshing();
 
     await refreshing;
 
@@ -105,10 +126,14 @@ function isExistsError(error: unknown): boolean {
   return error instanceof Error && 'code' in error && error.code === 'EEXIST';
 }
 
-// Moves the lock's age forward while it is still the directory this call
-// created, and resolves to the lock as it then stands; null leaves the
-// lock to go stale, as a holder that stopped refreshing it does.
-async function refreshOwnedLock(lockPath: string, owned: OwnedLock): Promise<OwnedLock | null> {
+// Moves the lock's age forward to the given time while it is still the
+// directory this call created, and resolves to the lock as it then stands;
+// null leaves the lock to go stale, as a holder that stopped refreshing it does.
+async function refreshOwnedLock(
+  lockPath: string,
+  owned: OwnedLock,
+  nowMs: number,
+): Promise<OwnedLock | null> {
   const isOwned = await isOwnedLock(lockPath, owned);
 
   if (!isOwned) {
@@ -116,7 +141,7 @@ async function refreshOwnedLock(lockPath: string, owned: OwnedLock): Promise<Own
   }
 
   try {
-    const now = new Date();
+    const now = new Date(nowMs);
 
     await utimes(lockPath, now, now);
 

package/src/agents/write-atc-bridge.ts

@@ -6,14 +6,17 @@ import { buildCLIArgv } from './build-cli-argv';
 
 /**
  * Writes the atc-bridge mod that every Claude session loads with
- * `--plugin-dir`, with the atc command it runs rendered for this install,
- * and returns its folder. A file whose content already matches is left
- * untouched, since any write reloads the mod in every running session, and
- * the folder is never cleared, since Claude Code keeps its own type files
- * there.
+ * `--plugin-dir`, with the atc command it runs rendered in (by default this
+ * install's own), and returns its folder. A file whose content already
+ * matches is left untouched, since any write reloads the mod in every running
+ * session, and the folder is never cleared, since Claude Code keeps its own
+ * type files there.
  */
-export function writeATCBridge(dir: string = join(stateDir, 'atc-bridge')): string {
-  const files = buildATCBridgeFiles(buildCLIArgv());
+export function writeATCBridge(
+  dir: string = join(stateDir, 'atc-bridge'),
+  argv: readonly string[] = buildCLIArgv(),
+): string {
+  const files = buildATCBridgeFiles(argv);
 
   for (const [path, content] of Object.entries(files)) {
     const file = join(dir, path);

package/src/agents/write-hook-settings.ts

@@ -8,13 +8,19 @@ import type { HookSettingsProfile } from './build-hook-settings';
 
 /**
  * Writes the settings file passed to a wrangled session as
- * `claude --settings`, one per agent id, and returns its path.
+ * `claude --settings`, one per agent id, into the folder `dir`, and returns
+ * its path. The statusline padding comes from the Claude settings in the
+ * user's home `homeDir`.
  */
-export function writeHookSettings(profile: HookSettingsProfile): string {
-  const file = join(stateDir, `hook-settings-${profile.id}.json`);
-  const settings = buildHookSettings(profile, readStatuslinePadding());
+export function writeHookSettings(
+  profile: HookSettingsProfile,
+  dir: string = stateDir,
+  homeDir: string = resolveHomeDir(),
+): string {
+  const file = join(dir, `hook-settings-${profile.id}.json`);
+  const settings = buildHookSettings(profile, readStatuslinePadding(homeDir));
 
-  mkdirSync(stateDir, { recursive: true });
+  mkdirSync(dir, { recursive: true });
   writeFileSync(file, JSON.stringify(settings, null, 2));
 
   return file;
@@ -24,9 +30,9 @@ export function writeHookSettings(profile: HookSettingsProfile): string {
  * The padding on the user's own statusline, so the chained one lines up with
  * it. An unreadable or unconfigured setting is no padding.
  */
-function readStatuslinePadding(): number {
+function readStatuslinePadding(homeDir: string): number {
   try {
-    const raw = readFileSync(join(resolveHomeDir(), '.claude', 'settings.json'), 'utf8');
+    const raw = readFileSync(join(homeDir, '.claude', 'settings.json'), 'utf8');
     const user: unknown = JSON.parse(raw);
     const statusLine = isRecord(user) ? user['statusLine'] : undefined;
     const padding = isRecord(statusLine) ? statusLine['padding'] : undefined;

package/src/client/boot-daemon.ts

@@ -11,6 +11,8 @@ import { getBuild } from '../shared/get-build';
 import { isProcessAlive } from '../shared/is-process-alive';
 import { makeSingleFlight } from '../shared/make-single-flight';
 import { spawnATCDetached } from '../shared/spawn-atc-detached';
+import { systemClock } from '../shared/system-clock';
+import type { Clock } from '../shared/system-clock';
 import { toAgentID } from '../shared/to-agent-id';
 import { DaemonClient } from './daemon-client';
 import { formatProtocolMismatch } from './format-protocol-mismatch';
@@ -30,6 +32,17 @@ export interface DaemonBoot {
   readonly socketPath: string;
 }
 
+/**
+ * The files that locate a running daemon: the socket this environment
+ * computes, the record the daemon writes in its state directory, and its
+ * pid file.
+ */
+export interface DaemonPaths {
+  readonly socketPath: string;
+  readonly recordFile: string;
+  readonly pidFile: string;
+}
+
 export interface DaemonBootOptions {
   // Called when the daemon speaks another protocol version. Resolving true
   // stops that daemon and boots one from this build, which ends every
@@ -42,8 +55,29 @@ export interface DaemonBootOptions {
   // manager starts beside a managed daemon sets it, so the two never race
   // for the state directory.
   readonly waitForDaemonMs?: number;
+
+  // Called once per boot, when a waiting boot first finds no daemon and
+  // starts to wait instead of starting one; a retry after a protocol
+  // mismatch that waits again does not call it a second time.
+  readonly onWaitForDaemon?: () => void;
+
+  // The time and the timers a waiting boot reads for its deadline and its
+  // polls; the wall clock when absent.
+  readonly clock?: Clock;
+
+  // Where the boot looks for a running daemon and its pid; this process's
+  // own paths when absent. `atc daemon` takes no paths of its own, only the
+  // environment's, so a boot given paths never starts a daemon: when none
+  // answers there, it rejects at once.
+  readonly paths?: DaemonPaths;
 }
 
+const PROCESS_PATHS: DaemonPaths = {
+  socketPath: daemonSocketPath,
+  recordFile: daemonRecordFile,
+  pidFile: daemonPidFile,
+};
+
 /**
  * Opens a handshaken client to the daemon, booting the daemon first when
  * neither the computed socket nor the one in the daemon's record answers,
@@ -59,14 +93,34 @@ export interface DaemonBootOptions {
  * its own boot would otherwise flag daemons that are already current.
  */
 export async function bootDaemonClient(options: DaemonBootOptions = {}): Promise<DaemonBoot> {
+  let waited = false;
+  const clock = options.clock ?? systemClock;
+  const paths = options.paths ?? PROCESS_PATHS;
+
   const wait =
     options.waitForDaemonMs === undefined
       ? null
-      : { deadline: Date.now() + options.waitForDaemonMs, timeoutMs: options.waitForDaemonMs };
+      : {
+          deadline: clock.now() + options.waitForDaemonMs,
+          timeoutMs: options.waitForDaemonMs,
+          clock,
+          paths,
+          onWait: () => {
+            if (!waited) {
+              waited = true;
+              options.onWaitForDaemon?.();
+            }
+          },
+        };
 
   for (let attempt = 0; attempt < 2; attempt++) {
     const build = getBuild();
-    const opened = wait === null ? await openOrBootDaemon() : await waitForDaemon(wait);
+
+    const opened =
+      wait === null
+        ? await openOrBootDaemon(paths, options.paths === undefined)
+        : await waitForDaemon(wait);
+
     const client = opened.client;
 
     try {
@@ -91,7 +145,7 @@ export async function bootDaemonClient(options: DaemonBootOptions = {}): Promise
 
       const mismatch: ProtocolMismatch = {
         socketPath: opened.socketPath,
-        daemonPID: findDaemonPID(opened.socketPath),
+        daemonPID: findDaemonPID(opened.socketPath, paths),
         clientBuild: build,
         clientProtocol: PROTOCOL_V,
         daemonMessage: error.message,
@@ -119,19 +173,28 @@ interface OpenedDaemon {
   readonly socketPath: string;
 }
 
-async function openOrBootDaemon(): Promise<OpenedDaemon> {
-  const opened = await tryOpenKnownDaemon();
+/**
+ * Opens the daemon at the known paths, starting one first when none
+ * answers and the boot may start one. A boot that may not start one, since
+ * a daemon it started would listen elsewhere, rejects instead.
+ */
+async function openOrBootDaemon(paths: DaemonPaths, canStart: boolean): Promise<OpenedDaemon> {
+  const opened = await tryOpenKnownDaemon(paths);
 
   if (opened !== null) {
     return opened;
   }
 
+  if (!canStart) {
+    throw new Error(formatGivenPathsFailure(paths));
+  }
+
   await bootDaemonOnce();
 
-  const booted = await tryOpenKnownDaemon();
+  const booted = await tryOpenKnownDaemon(paths);
 
   if (booted === null) {
-    throw new Error(formatBootFailure());
+    throw new Error(formatBootFailure(paths));
   }
 
   return booted;
@@ -142,24 +205,36 @@ async function openOrBootDaemon(): Promise<OpenedDaemon> {
 interface DaemonWait {
   readonly deadline: number;
   readonly timeoutMs: number;
+  readonly clock: Clock;
+  readonly paths: DaemonPaths;
+
+  // Called on every miss; the boot reports only the first to its caller.
+  readonly onWait: () => void;
 }
 
 /**
  * Polls the known sockets until a daemon answers, and never starts one.
+ * Each miss reports that the wait goes on.
  */
 async function waitForDaemon(wait: DaemonWait): Promise<OpenedDaemon> {
   for (;;) {
-    const opened = await tryOpenKnownDaemon();
+    const opened = await tryOpenKnownDaemon(wait.paths);
 
     if (opened !== null) {
       return opened;
     }
 
-    if (Date.now() >= wait.deadline) {
-      throw new Error(formatWaitFailure(wait.timeoutMs));
+    wait.onWait();
+
+    if (wait.clock.now() >= wait.deadline) {
+      throw new Error(formatWaitFailure(wait));
     }
 
-    await Bun.sleep(100);
+    const polled = Promise.withResolvers<void>();
+
+    wait.clock.schedule(polled.resolve, 100);
+
+    await polled.promise;
   }
 }
 
@@ -172,21 +247,19 @@ async function waitForHello(
   sendHello: () => Promise<Readonly<Record<string, unknown>>>,
   wait: DaemonWait,
 ): Promise<Readonly<Record<string, unknown>>> {
-  let timer: ReturnType<typeof setTimeout> | undefined;
-
-  const expired = new Promise<never>((_resolve, reject) => {
-    timer = setTimeout(
-      () => {
-        reject(new Error(formatWaitFailure(wait.timeoutMs)));
-      },
-      Math.max(0, wait.deadline - Date.now()),
-    );
-  });
+  const expired = Promise.withResolvers<never>();
+
+  const cancel = wait.clock.schedule(
+    () => {
+      expired.reject(new Error(formatWaitFailure(wait)));
+    },
+    Math.max(0, wait.deadline - wait.clock.now()),
+  );
 
   try {
-    return await Promise.race([sendHello(), expired]);
+    return await Promise.race([sendHello(), expired.promise]);
   } finally {
-    clearTimeout(timer);
+    cancel();
   }
 }
 
@@ -195,16 +268,16 @@ async function waitForHello(
  * daemon recorded in the state directory: a client whose environment lacks
  * XDG_RUNTIME_DIR computes a different path from the daemon's.
  */
-async function tryOpenKnownDaemon(): Promise<OpenedDaemon | null> {
-  const computed = await tryOpenDaemon(daemonSocketPath);
+async function tryOpenKnownDaemon(paths: DaemonPaths): Promise<OpenedDaemon | null> {
+  const computed = await tryOpenDaemon(paths.socketPath);
 
   if (computed !== null) {
     return computed;
   }
 
-  const record = findDaemonRecord(daemonRecordFile);
+  const record = findDaemonRecord(paths.recordFile);
 
-  if (record === null || record.socketPath === daemonSocketPath) {
+  if (record === null || record.socketPath === paths.socketPath) {
     return null;
   }
 
@@ -230,7 +303,7 @@ const bootDaemonOnce = makeSingleFlight(async () => {
   while (Date.now() < deadline) {
     await Bun.sleep(100);
 
-    const probe = await tryOpenKnownDaemon();
+    const probe = await tryOpenKnownDaemon(PROCESS_PATHS);
 
     if (probe !== null) {
       probe.client.stop();
@@ -249,14 +322,24 @@ const bootDaemonOnce = makeSingleFlight(async () => {
 // A live daemon this process cannot reach, such as one whose runtime
 // directory a sandbox hides, needs a different fix than one that never
 // started, so the message tells them apart.
-function formatBootFailure(): string {
+function formatBootFailure(paths: DaemonPaths): string {
+  return (
+    formatUnreachableDaemon(paths) ??
+    'the atc daemon did not come up; try `atc daemon` for its output'
+  );
+}
+
+// A boot given its own paths starts no daemon, since `atc daemon` would
+// listen at this process's paths instead, so the message says so.
+function formatGivenPathsFailure(paths: DaemonPaths): string {
   return (
-    formatUnreachableDaemon() ?? 'the atc daemon did not come up; try `atc daemon` for its output'
+    formatUnreachableDaemon(paths) ??
+    `no atc daemon answered at ${paths.socketPath}, and a boot given its own daemon paths does not start one; start \`atc daemon\` where it listens there first`
   );
 }
 
-function formatUnreachableDaemon(): string | null {
-  const record = findDaemonRecord(daemonRecordFile);
+function formatUnreachableDaemon(paths: DaemonPaths): string | null {
+  const record = findDaemonRecord(paths.recordFile);
 
   if (record !== null && isProcessAlive(record.pid)) {
     return `the atc daemon (pid ${record.pid}) is running, but its socket ${record.socketPath} is unreachable from here`;
@@ -267,20 +350,20 @@ function formatUnreachableDaemon(): string | null {
 
 // A waiting caller was told not to start a daemon, so the message says so
 // and points at starting the managed one.
-function formatWaitFailure(timeoutMs: number): string {
+function formatWaitFailure(wait: DaemonWait): string {
   return (
-    formatUnreachableDaemon() ??
-    `no atc daemon answered at ${daemonSocketPath} within ${timeoutMs / 1000}s, and this process does not start one; start \`atc daemon\` (or the service that runs it) first`
+    formatUnreachableDaemon(wait.paths) ??
+    `no atc daemon answered at ${wait.paths.socketPath} within ${wait.timeoutMs / 1000}s, and this process does not start one; start \`atc daemon\` (or the service that runs it) first`
   );
 }
 
 // The pid of the daemon behind the socket that refused the handshake.
-function findDaemonPID(socketPath: string): number | null {
+function findDaemonPID(socketPath: string, paths: DaemonPaths): number | null {
   return pickStaleDaemonPID({
     socketPath,
-    record: findDaemonRecord(daemonRecordFile),
-    pidFileSocketPath: daemonSocketPath,
-    pidFilePID: findPidFilePID(daemonPidFile),
+    record: findDaemonRecord(paths.recordFile),
+    pidFileSocketPath: paths.socketPath,
+    pidFilePID: findPidFilePID(paths.pidFile),
   });
 }
 

package/src/client/dirs.ts

@@ -8,13 +8,15 @@ import { collectRootDirs } from '../shared/collect-root-dirs';
  * to find a directory: where the client runs, then the daemon's spawn
  * history (most recent first), then the configured roots, then zoxide's
  * frecency list. A path that no longer exists is dropped, a duplicate keeps
- * its first position, and an empty merge falls back to the home directory.
+ * its first position, and an empty merge falls back to the home directory:
+ * `home` when given, otherwise the account's.
  */
 export interface DirSources {
   readonly cwd: string;
   readonly recent: readonly string[];
   readonly roots: readonly string[];
   readonly zoxide: readonly string[];
+  readonly home?: string;
 }
 
 export function collectDirs(sources: DirSources): string[] {
@@ -35,7 +37,7 @@ export function collectDirs(sources: DirSources): string[] {
   }
 
   if (found.length === 0) {
-    found.push(homedir());
+    found.push(sources.home ?? homedir());
   }
 
   return found;

package/src/client/index.ts

@@ -7,7 +7,7 @@ import type { EventMsg } from '../protocol/protocol';
 import { sortGroupedSessionViews } from '../protocol/sort-grouped-session-views';
 import { sortSessionViews } from '../protocol/sort-session-views';
 import type { AgentID } from '../shared/agent-id';
-import { loadConfig } from '../shared/config';
+import { configFile, loadConfig } from '../shared/config';
 import { makeSingleFlight } from '../shared/make-single-flight';
 import { bootDaemonClient } from './boot-daemon';
 import { buildClientMachine } from './build-client-machine';
@@ -16,6 +16,7 @@ import { collectTargetPicks } from './collect-target-picks';
 import { findFuzzyScore, formatDir } from './dirs';
 import type { ProtocolMismatch } from './format-protocol-mismatch';
 import { KEY, isDown, isUp, planTextEdit } from './keys';
+import { logClientEvent } from './log-client-event';
 import { parseDaemonEvent } from './parse-daemon-event';
 import { pickTabTarget } from './pick-tab-target';
 import { resolveAgentMetadata } from './resolve-agent-metadata';
@@ -341,6 +342,15 @@ const picker = new SpawnPicker<MirrorSession>({
   toMirrorSession,
   upsertMirror,
   hasDaemonFeature,
+  write: (chunk) => {
+    process.stdout.write(chunk);
+  },
+  cwd: process.cwd(),
+  configPath: configFile,
+  onDropAnswer: (kind) => {
+    logClientEvent(`dropped ${kind} answer`);
+  },
+  log: logClientEvent,
 });
 
 function openPicker(resume: boolean) {
@@ -721,6 +731,12 @@ function applyOverlayKey(buf: Buffer) {
     return;
   }
 
+  if (ch === 'H') {
+    logClientEvent('ignored H on a session that cannot eject');
+
+    return;
+  }
+
   if (ch === 'P' && sel !== undefined && sel.resumable && (sel.kind === 'headless' || !sel.alive)) {
     void adoptSession(sel.id);
 

package/src/client/log-client-event.ts

@@ -0,0 +1,20 @@
+import { appendFileSync } from 'node:fs';
+
+/**
+ * Appends one line, a decision the client took without drawing anything, to
+ * the file `ATC_CLIENT_LOG` holds, and does nothing when the variable is
+ * unset or empty. A write that fails is dropped, so the log never stops the
+ * client. It writes off the screen because the client's stdout and stderr
+ * are the terminal it draws on.
+ */
+export function logClientEvent(line: string): void {
+  const path = process.env['ATC_CLIENT_LOG'];
+
+  if (path === undefined || path === '') {
+    return;
+  }
+
+  try {
+    appendFileSync(path, `${line}\n`);
+  } catch {}
+}