@zgeoff/atc 3.4.0 → 3.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgeoff/atc",
-  "version": "3.4.0",
+  "version": "3.4.2",
   "description": "Terminal control tower for coding-agent sessions",
   "homepage": "https://github.com/zgeoff/atc#readme",
   "bugs": "https://github.com/zgeoff/atc/issues",
@@ -31,7 +31,7 @@
     "test": "bash scripts/with-test-home.sh bun test --parallel --timings=bun-test-timings.json",
     "test:timings": "bash scripts/with-test-home.sh bun test --parallel --timings=bun-test-timings.json --update-timings",
     "test:binary": "bash scripts/with-test-home.sh bun test --timeout 20000 e2e/daemon-*.test.ts",
-    "test:gateway-binary": "bash scripts/with-test-home.sh bun test --timeout 20000 src/gateway.test.ts",
+    "test:gateway-binary": "bash scripts/with-test-home.sh bun test --timeout 20000 e2e/gateway-*.test.ts",
     "test:atc-bridge": "bash scripts/with-test-home.sh bash scripts/test-atc-bridge.sh",
     "test:isolation": "bash scripts/check-test-isolation.sh",
     "typecheck": "tsc -p tsconfig.json --noEmit",

package/src/agents/build-agent-adapters.ts

@@ -1,11 +1,20 @@
 import type { Config } from '../shared/config';
-import type { AgentAdapter } from './agent-adapter';
+import type { AgentAdapter, ClaudeHostPaths } from './agent-adapter';
 import { ClaudeAdapter } from './claude-adapter';
 import { CodexAdapter } from './codex-adapter';
 import { GatewayAdapter } from './gateway-adapter';
 import { GrokAdapter } from './grok-adapter';
 import type { ClaudeHeadlessRun } from './make-claude-headless-runner';
 
+/**
+ * Where the Claude and gateway adapters write their settings file and their
+ * copy of the atc-bridge mod, and the home whose Claude config they read. A
+ * field left out takes atc's state folder or the running user's home.
+ */
+interface AgentAdapterPaths extends ClaudeHostPaths {
+  readonly bridgeTarget?: string;
+}
+
 /**
  * One adapter per registry entry, in registry order. A Claude entry with a
  * base URL is a gateway, and one without is stock Claude.
@@ -13,7 +22,10 @@ import type { ClaudeHeadlessRun } from './make-claude-headless-runner';
 export function buildAgentAdapters(
   config: Config,
   headlessRun: ClaudeHeadlessRun | null = null,
+  paths: AgentAdapterPaths = {},
 ): AgentAdapter[] {
+  const { bridgeTarget, ...hostPaths } = paths;
+
   return config.agents.map((entry): AgentAdapter => {
     if (entry.kind === 'codex') {
       return new CodexAdapter(entry, config);
@@ -24,9 +36,15 @@ export function buildAgentAdapters(
     }
 
     if (entry.baseURL === undefined) {
-      return new ClaudeAdapter(entry, config, headlessRun);
+      return new ClaudeAdapter(entry, config, headlessRun, bridgeTarget, hostPaths);
     }
 
-    return new GatewayAdapter({ ...entry, baseURL: entry.baseURL }, config, headlessRun);
+    return new GatewayAdapter(
+      { ...entry, baseURL: entry.baseURL },
+      config,
+      headlessRun,
+      bridgeTarget,
+      hostPaths,
+    );
   });
 }

package/src/agents/claude-adapter.ts

@@ -48,7 +48,7 @@ import { loadClaudeConfigBundle } from './load-claude-config-bundle';
 import { makeClaudeHeadlessRunner } from './make-claude-headless-runner';
 import type { ClaudeHeadlessRun } from './make-claude-headless-runner';
 import { parseClaudeTranscriptLine } from './parse-claude-transcript-line';
-import { planPastedLineInput } from './plan-pasted-line-input';
+import { planClaudeLineInput } from './plan-claude-line-input';
 import { resolveAgentHome } from './resolve-agent-home';
 import { resolveClaudeGlobalConfigPath } from './resolve-claude-global-config-path';
 import { resolveClaudePermissionMode } from './resolve-claude-permission-mode';
@@ -88,8 +88,9 @@ export class ClaudeAdapter implements AgentAdapter {
   readonly parseTranscriptLine = parseClaudeTranscriptLine;
 
   // Claude's TUI takes a long burst of input as a paste and keeps its
-  // newline in the composer, so a line is pasted and then submitted.
-  readonly planLineInput = planPastedLineInput;
+  // newline in the composer, so a line is pasted and then submitted, with a
+  // leading slash command's name typed so the command still runs.
+  readonly planLineInput = planClaudeLineInput;
 
   readonly profile: AgentProfile;
 

package/src/agents/codex-adapter.ts

@@ -53,6 +53,11 @@ type CodexHookPayload = z.infer<typeof CODEX_HOOK_PAYLOAD_SCHEMA>;
 // The spellings of the Codex CLI's model flag.
 const CODEX_MODEL_FLAGS = ['-m', '--model'];
 
+// The Codex CLI flag that runs a terminal without the shared background
+// server, and the flag that connects it to a remote server instead.
+const NO_DAEMON_FLAG = '--no-daemon';
+const REMOTE_FLAG = '--remote';
+
 /**
  * The Codex CLI adapter: spawn arguments, hook payload mapping, resume
  * semantics, and session_index.jsonl name-pulling. Hooks are a user-installed
@@ -118,6 +123,14 @@ export class CodexAdapter implements AgentAdapter {
     return {
       bin: this.entry.bin,
       args: [
+        // Codex's shared background server keeps the environment of the
+        // terminal that started it and runs every thread's hooks and tools
+        // there, so a terminal on it reports as that first session. Each
+        // terminal therefore runs its own server. The configured arguments
+        // already carry the flag, or connect to a remote server, which Codex
+        // refuses to combine with it; either way Codex takes no second copy.
+        ...(this.entry.args.some(isDaemonChoiceFlag) ? [] : [NO_DAEMON_FLAG]),
+
         // A model override replaces any model flag the configured arguments
         // carry, and travels as its own argument.
         ...(opts.model === undefined
@@ -420,3 +433,10 @@ function buildCodexSpawnOptions(codexArgs: readonly string[]): SpawnOptionSpecs
     },
   };
 }
+
+// Whether a configured argument already decides which server a terminal
+// uses: the flag that runs it without the shared one, or the remote server
+// flag in either of its spellings.
+function isDaemonChoiceFlag(arg: string): boolean {
+  return arg === NO_DAEMON_FLAG || arg === REMOTE_FLAG || arg.startsWith(`${REMOTE_FLAG}=`);
+}

package/src/agents/gateway-adapter.ts

@@ -38,7 +38,7 @@ import { findFlagValue } from './find-flag-value';
 import { makeClaudeHeadlessRunner } from './make-claude-headless-runner';
 import type { ClaudeHeadlessRun } from './make-claude-headless-runner';
 import { parseClaudeTranscriptLine } from './parse-claude-transcript-line';
-import { planPastedLineInput } from './plan-pasted-line-input';
+import { planClaudeLineInput } from './plan-claude-line-input';
 import { resolveClaudePermissionMode } from './resolve-claude-permission-mode';
 import { writeATCBridge } from './write-atc-bridge';
 import { writeHookSettings } from './write-hook-settings';
@@ -68,7 +68,7 @@ export class GatewayAdapter implements AgentAdapter {
   readonly parseTranscriptLine = parseClaudeTranscriptLine;
 
   // The gateway runs the Claude CLI, whose TUI takes a line the same way.
-  readonly planLineInput = planPastedLineInput;
+  readonly planLineInput = planClaudeLineInput;
 
   readonly takesMessages = true;
 

package/src/agents/plan-claude-line-input.ts

@@ -0,0 +1,44 @@
+import type { TerminalInputModes } from './agent-adapter';
+import { planPastedLineInput } from './plan-pasted-line-input';
+
+const PASTE_START = '\u001B[200~';
+const PASTE_END = '\u001B[201~';
+
+/**
+ * Pastes a line into the Claude TUI and submits it, as the pasted line
+ * planner does, except for a line that opens with a slash command and an
+ * argument. Claude takes a long paste as pasted text and sends it as a
+ * message, so such a line has its command name and the spaces after it typed
+ * as keys and only the argument pasted, then one carriage return. The
+ * command then runs at any argument length. A TUI that has not turned
+ * bracketed paste on gets every line as the pasted line planner writes it.
+ */
+export function planClaudeLineInput(text: string, modes: TerminalInputModes): readonly string[] {
+  const unmarked = text.replaceAll(PASTE_START, '').replaceAll(PASTE_END, '');
+  const command = modes.bracketedPaste ? findSlashCommand(unmarked) : null;
+
+  if (command === null) {
+    return planPastedLineInput(text, modes);
+  }
+
+  return [command.typed, `${PASTE_START}${command.argument}${PASTE_END}`, '\r'];
+}
+
+// A slash, a command name that may hold a plugin namespace, at least one
+// space, then the argument. A path such as `/tmp/out` has a slash after its
+// first name, so it never matches.
+const SLASH_COMMAND = /^(?<typed>\/[A-Za-z0-9][\w:-]* +)(?<argument>.+)$/su;
+
+function findSlashCommand(text: string): { typed: string; argument: string } | null {
+  const groups = SLASH_COMMAND.exec(text)?.groups;
+  const typed = groups?.['typed'];
+  const argument = groups?.['argument'];
+
+  // An argument of spaces alone leaves a bare command, which the line
+  // pastes whole like any short line.
+  if (typed === undefined || argument === undefined || argument.trim() === '') {
+    return null;
+  }
+
+  return { typed, argument };
+}

package/src/agents/render-sdk-message.ts

@@ -0,0 +1,57 @@
+import { isRecord } from '../shared/report';
+import { truncateSummary } from '../shared/truncate-summary';
+
+interface RenderableMessage {
+  readonly type: string;
+  readonly subtype?: string;
+  readonly result?: string;
+  readonly message?: unknown;
+}
+
+/**
+ * One structured SDK message → zero or one plain-text line for the session's
+ * output pipe: assistant text verbatim, tool calls as compact one-liners,
+ * results as a closing line.
+ */
+export function renderSDKMessage(message: RenderableMessage): string | null {
+  if (message.type === 'assistant') {
+    const inner = message.message;
+
+    if (!isRecord(inner) || !Array.isArray(inner['content'])) {
+      return null;
+    }
+
+    const content = inner['content'];
+    const lines: string[] = [];
+
+    for (const raw of content) {
+      const block: unknown = raw;
+
+      if (!isRecord(block)) {
+        continue;
+      }
+
+      if (
+        block['type'] === 'text' &&
+        typeof block['text'] === 'string' &&
+        block['text'].trim() !== ''
+      ) {
+        lines.push(block['text'].replaceAll('\n', '\r\n'));
+      }
+
+      if (block['type'] === 'tool_use' && typeof block['name'] === 'string') {
+        lines.push(`⚙ ${block['name']} ${truncateSummary(JSON.stringify(block['input'] ?? {}))}`);
+      }
+    }
+
+    return lines.length === 0 ? null : lines.join('\r\n');
+  }
+
+  if (message.type === 'result') {
+    return message.subtype === 'success'
+      ? `— headless turn done: ${truncateSummary(message.result ?? '')}`
+      : `— headless turn stopped: ${message.subtype ?? 'unknown'}`;
+  }
+
+  return null;
+}

package/src/agents/start-claude-headless-run.ts

@@ -1,8 +1,8 @@
 import { isCompiledBinary } from '../shared/is-compiled-binary';
-import { isRecord } from '../shared/report';
 import { truncateSummary } from '../shared/truncate-summary';
 import { buildClaudeQueryOptions } from './build-claude-query-options';
 import type { ClaudeHeadlessRunRequest } from './build-claude-query-options';
+import { renderSDKMessage } from './render-sdk-message';
 
 interface HeadlessRunHooks {
   readonly onOutput: (text: string) => void;
@@ -47,7 +47,7 @@ export function startClaudeHeadlessRun(
       });
 
       for await (const message of stream) {
-        const rendered = renderSdkMessage(message);
+        const rendered = renderSDKMessage(message);
 
         if (rendered !== null) {
           hooks.onOutput(`${rendered}\r\n`);
@@ -84,58 +84,3 @@ export function startClaudeHeadlessRun(
     },
   };
 }
-
-interface RenderableMessage {
-  readonly type: string;
-  readonly subtype?: string;
-  readonly result?: string;
-  readonly message?: unknown;
-}
-
-/**
- * One structured SDK message → zero or one plain-text line for the session's
- * output pipe: assistant text verbatim, tool calls as compact one-liners,
- * results as a closing line.
- */
-export function renderSdkMessage(message: RenderableMessage): string | null {
-  if (message.type === 'assistant') {
-    const inner = message.message;
-
-    if (!isRecord(inner) || !Array.isArray(inner['content'])) {
-      return null;
-    }
-
-    const content = inner['content'];
-    const lines: string[] = [];
-
-    for (const raw of content) {
-      const block: unknown = raw;
-
-      if (!isRecord(block)) {
-        continue;
-      }
-
-      if (
-        block['type'] === 'text' &&
-        typeof block['text'] === 'string' &&
-        block['text'].trim() !== ''
-      ) {
-        lines.push(block['text'].replaceAll('\n', '\r\n'));
-      }
-
-      if (block['type'] === 'tool_use' && typeof block['name'] === 'string') {
-        lines.push(`⚙ ${block['name']} ${truncateSummary(JSON.stringify(block['input'] ?? {}))}`);
-      }
-    }
-
-    return lines.length === 0 ? null : lines.join('\r\n');
-  }
-
-  if (message.type === 'result') {
-    return message.subtype === 'success'
-      ? `— headless turn done: ${truncateSummary(message.result ?? '')}`
-      : `— headless turn stopped: ${message.subtype ?? 'unknown'}`;
-  }
-
-  return null;
-}

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.
@@ -13,11 +15,12 @@ const WAIT_MS = 5000;
 const RETRY_MS = 50;
 
 /**
- * Tuning a caller may pass: how often a held lock's age is refreshed, and a
- * callback run each time the lock is found held by someone else.
+ * 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 refreshMs?: number;
+  readonly clock?: Clock;
   readonly onBusy?: () => void;
 }
 
@@ -55,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;
-    })();
-  }, options.refreshMs ?? REFRESH_MS);
+        owned = refreshed ?? owned;
+      })();
+
+      stopRefreshing = scheduleRefresh();
+    }, REFRESH_MS);
+
+  let stopRefreshing = scheduleRefresh();
 
   try {
     return await run();
   } finally {
-    clearInterval(timer);
+    stopRefreshing();
 
     await refreshing;
 
@@ -117,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) {
@@ -128,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/client/boot-daemon.ts

@@ -32,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
@@ -53,8 +64,20 @@ export interface DaemonBootOptions {
   // 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,
@@ -72,6 +95,7 @@ export interface DaemonBootOptions {
 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
@@ -80,6 +104,7 @@ export async function bootDaemonClient(options: DaemonBootOptions = {}): Promise
           deadline: clock.now() + options.waitForDaemonMs,
           timeoutMs: options.waitForDaemonMs,
           clock,
+          paths,
           onWait: () => {
             if (!waited) {
               waited = true;
@@ -90,7 +115,12 @@ export async function bootDaemonClient(options: DaemonBootOptions = {}): Promise
 
   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 {
@@ -115,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,
@@ -143,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;
@@ -167,6 +206,7 @@ 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;
@@ -178,7 +218,7 @@ interface DaemonWait {
  */
 async function waitForDaemon(wait: DaemonWait): Promise<OpenedDaemon> {
   for (;;) {
-    const opened = await tryOpenKnownDaemon();
+    const opened = await tryOpenKnownDaemon(wait.paths);
 
     if (opened !== null) {
       return opened;
@@ -187,7 +227,7 @@ async function waitForDaemon(wait: DaemonWait): Promise<OpenedDaemon> {
     wait.onWait();
 
     if (wait.clock.now() >= wait.deadline) {
-      throw new Error(formatWaitFailure(wait.timeoutMs));
+      throw new Error(formatWaitFailure(wait));
     }
 
     const polled = Promise.withResolvers<void>();
@@ -211,7 +251,7 @@ async function waitForHello(
 
   const cancel = wait.clock.schedule(
     () => {
-      expired.reject(new Error(formatWaitFailure(wait.timeoutMs)));
+      expired.reject(new Error(formatWaitFailure(wait)));
     },
     Math.max(0, wait.deadline - wait.clock.now()),
   );
@@ -228,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;
   }
 
@@ -263,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();
@@ -282,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`;
@@ -300,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/resolve-workspace-root.ts

@@ -21,13 +21,18 @@ const DEFAULT_ROOT = '~/.local/share/atc/workspaces';
  * root, else the global root, else the default. On the daemon's own
  * machine a leading `~` expands to the home directory. On any other target
  * the root must be absolute, since `~` there is a home this client cannot
- * see, so a root that is not is refused with the config key to set.
+ * see, so a root that is not is refused with the config key to set. The
+ * home directory defaults to the user's own.
  */
-export function resolveWorkspaceRoot(config: WorkspacesConfig, target: RootTarget): WorkspaceRoot {
+export function resolveWorkspaceRoot(
+  config: WorkspacesConfig,
+  target: RootTarget,
+  home: string = resolveHomeDir(),
+): WorkspaceRoot {
   const configured = config.targetRoots.get(target.id) ?? config.root;
 
   if (target.inPlace) {
-    const root = expandHome(configured ?? DEFAULT_ROOT);
+    const root = expandHome(configured ?? DEFAULT_ROOT, home);
 
     return root.startsWith('/')
       ? { ok: true, root }
@@ -44,6 +49,6 @@ export function resolveWorkspaceRoot(config: WorkspacesConfig, target: RootTarge
   return { ok: true, root: configured };
 }
 
-function expandHome(dir: string): string {
-  return dir === '~' || dir.startsWith('~/') ? `${resolveHomeDir()}${dir.slice(1)}` : dir;
+function expandHome(dir: string, home: string): string {
+  return dir === '~' || dir.startsWith('~/') ? `${home}${dir.slice(1)}` : dir;
 }