@zgeoff/atc 2.33.0 → 2.34.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgeoff/atc",
-  "version": "2.33.0",
+  "version": "2.34.0",
   "description": "Terminal control tower for coding-agent sessions",
   "homepage": "https://github.com/zgeoff/atc#readme",
   "bugs": "https://github.com/zgeoff/atc/issues",

package/src/cli.ts

@@ -452,6 +452,7 @@ async function runDaemon(listenArg: string | null, tokenFile: string | null): Pr
       principals: cfg.principals,
       sources: sources.sources,
       gitTransports: cfg.workspaces.gitTransports,
+      workspaceRoots: { root: cfg.workspaces.root, targetRoots: cfg.workspaces.targetRoots },
       ...(listen === null || tokenFile === null
         ? {}
         : { listen: { host: listen.host, port: listen.port, tokenFile } }),

package/src/client/index.ts

@@ -2,6 +2,7 @@ import { match } from 'ts-pattern';
 import { createActor } from 'xstate';
 import { countSessionStates } from '../protocol/count-session-states';
 import { DaemonError } from '../protocol/daemon-error';
+import type { DaemonFeature } from '../protocol/daemon-features';
 import type { EventMsg } from '../protocol/protocol';
 import { sortGroupedSessionViews } from '../protocol/sort-grouped-session-views';
 import { sortSessionViews } from '../protocol/sort-session-views';
@@ -339,12 +340,17 @@ const picker = new SpawnPicker<MirrorSession>({
   attach,
   toMirrorSession,
   upsertMirror,
+  hasDaemonFeature,
 });
 
 function openPicker(resume: boolean) {
   picker.open(resume);
 }
 
+function hasDaemonFeature(feature: DaemonFeature): boolean {
+  return daemonFeatures.has(feature);
+}
+
 function sendRequest(m: string, p?: Readonly<Record<string, unknown>>) {
   return client.sendRequest(m, p);
 }
@@ -832,6 +838,7 @@ const boot = await bootDaemonClient({
 
 let client = boot.client;
 let daemonStale = boot.stale;
+let daemonFeatures = boot.features;
 let daemonRestarting = false;
 
 lastUsedAgent = boot.lastUsedAgent;
@@ -950,6 +957,7 @@ async function restartDaemon() {
 
   client = next.client;
   daemonStale = next.stale;
+  daemonFeatures = next.features;
   lastUsedAgent = next.lastUsedAgent;
   client.onEvent = applyDaemonEvent;
 

package/src/client/spawn-picker.ts

@@ -1,6 +1,8 @@
 import { homedir } from 'node:os';
 import { DaemonError } from '../protocol/daemon-error';
+import type { DaemonFeature } from '../protocol/daemon-features';
 import type { AgentID } from '../shared/agent-id';
+import { buildWorkspaceDestination } from '../shared/build-workspace-destination';
 import type { WorkspacesConfig } from '../shared/collect-workspaces-config';
 import { collectZoxideDirs } from '../shared/collect-zoxide-dirs';
 import { loadConfig } from '../shared/config';
@@ -8,7 +10,6 @@ import { DEFAULT_GIT_TRANSPORTS } from '../shared/default-git-transports';
 import { isGitURL } from '../shared/is-git-url';
 import { isRecord } from '../shared/report';
 import { resolveHomeDir } from '../shared/resolve-home-dir';
-import { buildWorkspaceDestination } from './build-workspace-destination';
 import { collectAgentPicks } from './collect-agent-picks';
 import type { AgentPick } from './collect-agent-picks';
 import { collectPathCompletions } from './collect-path-completions';
@@ -48,6 +49,7 @@ export interface SpawnPickerDeps<TMirror> {
   readonly attach: (sessionID: string) => Promise<void>;
   readonly toMirrorSession: (value: unknown) => TMirror | null;
   readonly upsertMirror: (session: Readonly<TMirror>) => void;
+  readonly hasDaemonFeature: (feature: DaemonFeature) => boolean;
 }
 
 // One source `agents.list` returned, in the order the daemon offers them.
@@ -100,6 +102,9 @@ interface ChosenRef {
   readonly sha: string;
 }
 
+// The root the daemon picks a destination under on a remote target without
+// a configured one, as the confirm screen shows it.
+const AUTO_ROOT = '~/.local/share/atc/workspaces';
 const FULL_SHA_PATTERN = /^(?:[\da-f]{40}|[\da-f]{64})$/u;
 const SHORT_SHA_PATTERN = /^[\da-f]{7,63}$/u;
 
@@ -236,6 +241,11 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
   // The repository the destination was built or typed for.
   private destinationRepoURL: string | null = null;
 
+  // The directory the daemon picks on the target when the confirm screen
+  // has no destination it can build, under the target user's home as the
+  // screen shows it, or null when the spawn gives its own.
+  private autoDestination: string | null = null;
+
   private name = '';
 
   private resume = false;
@@ -291,6 +301,7 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
     this.destination = '';
     this.destinationEdited = false;
     this.destinationRepoURL = null;
+    this.autoDestination = null;
 
     // A last-used agent that is no longer installed is not in the menu, so
     // the selection falls to the first one that is.
@@ -462,7 +473,7 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
         items: [],
         selected: -1,
         input: this.input,
-        placeholder: formatDirName(this.dir),
+        placeholder: formatDirName(this.autoDestination ?? this.dir),
         hint: this.refusal ?? `session name for ${where} · ⏎ accept · esc back`,
       });
     } else {
@@ -607,7 +618,10 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
       ],
       selected: -1,
       input: this.input,
-      placeholder: 'destination on the target',
+      placeholder:
+        this.autoDestination === null
+          ? 'destination on the target'
+          : 'picked on the target · or type an absolute path',
       hint: this.refusal ?? 'destination on the target · ⏎ continue · esc back',
     });
   }
@@ -1584,6 +1598,7 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
   private openConfirmStep() {
     this.step = 'confirm';
     this.destinationAttempt = 1;
+    this.autoDestination = null;
 
     if (this.destination === '' && this.repo !== null && this.ref !== null) {
       const target = this.findEffectiveTarget();
@@ -1602,6 +1617,13 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
           ref: this.ref.ref,
           sha: this.ref.sha,
         });
+      } else if (target !== null && !target.inPlace && this.canPickOnTarget(target.id)) {
+        this.autoDestination = buildWorkspaceDestination({
+          root: this.workspaces.targetRoots.get(target.id) ?? this.workspaces.root ?? AUTO_ROOT,
+          url: this.repo.url,
+          ref: this.ref.ref,
+          sha: this.ref.sha,
+        });
       } else {
         this.refusal = root.message;
       }
@@ -1610,10 +1632,30 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
     this.input = this.buildDestination();
   }
 
+  // Whether the daemon picks the destination on a remote target: it must
+  // take a git workspace without a directory, and the target's configured
+  // root, if any, must be one it resolves there, under the home.
+  private canPickOnTarget(target: string): boolean {
+    const configured = this.workspaces.targetRoots.get(target) ?? this.workspaces.root;
+
+    return (
+      this.deps.hasDaemonFeature('spawn.workspace.autoDir') &&
+      (configured === null || configured === '~' || configured.startsWith('~/'))
+    );
+  }
+
   // Takes the confirm screen's destination: absolute on its target, with a
   // leading `~` expanded only on the daemon's own machine. False, with the
   // reason shown, when the target cannot take it.
   private applyDestination(typed: string): boolean {
+    // An empty destination takes the one the daemon picks on the target.
+    if (typed === '' && this.autoDestination !== null) {
+      this.destinationRepoURL = this.repo?.url ?? null;
+      this.dir = '';
+
+      return true;
+    }
+
     const inPlace = this.findEffectiveTarget()?.inPlace ?? true;
 
     const dir =
@@ -1635,6 +1677,7 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
       this.destinationEdited = true;
     }
 
+    this.autoDestination = null;
     this.destinationRepoURL = this.repo?.url ?? null;
     this.dir = this.buildDestination();
 
@@ -1649,7 +1692,11 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
   }
 
   private formatDestination(): string {
-    return `${this.findEffectiveTarget()?.id ?? 'local'}:${this.buildDestination()}`;
+    const target = this.findEffectiveTarget()?.id ?? 'local';
+
+    return this.autoDestination === null
+      ? `${target}:${this.buildDestination()}`
+      : `${target}:${this.autoDestination}`;
   }
 
   // The target the spawn runs on: the chosen one, else the daemon's
@@ -1792,7 +1839,7 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
 
   private async spawn(prompt: string) {
     const params = {
-      cwd: this.dir,
+      ...(this.isGitFlow() && this.autoDestination !== null ? {} : { cwd: this.dir }),
       name: this.name,
       prompt,
       cols: cols(),
@@ -1885,7 +1932,12 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
       return;
     }
 
-    if (step === 'destination') {
+    if (step === 'destination' && this.autoDestination !== null) {
+      // The daemon already tried the numbered directories beside its pick.
+      this.step = 'confirm';
+      this.input = '';
+      this.refusal = `${reason} · esc back`;
+    } else if (step === 'destination') {
       this.destinationAttempt += 1;
       this.step = 'confirm';
       this.input = this.buildDestination();

package/src/daemon/build-default-workspace-dir.ts

@@ -0,0 +1,70 @@
+import { posix } from 'node:path';
+import { DaemonError } from '../protocol/daemon-error';
+import type { SpawnWorkspaceSource } from '../protocol/request-param-schemas';
+import { buildWorkspaceDestination } from '../shared/build-workspace-destination';
+
+type GitWorkspaceSource = Extract<SpawnWorkspaceSource, { kind: 'git' }>;
+
+interface DefaultDirTarget {
+  // The workspaces root the config sets for the target, else the global
+  // one, else null for the default.
+  readonly root: string | null;
+
+  // Whether the target runs on another machine, whose home only that
+  // machine knows.
+  readonly remote: boolean;
+
+  // The home directory of the daemon's own user.
+  readonly home: string;
+}
+
+// Where checkouts land without a configured root, under the target user's
+// home.
+const DEFAULT_ROOT = '~/.local/share/atc/workspaces';
+
+/**
+ * The directory a git workspace lands in when the spawn gives none:
+ * `<root>/<repo>-<ref>-<short sha>`, with the root the config sets, else
+ * `~/.local/share/atc/workspaces`. A root under `~` resolves on the
+ * target: against the daemon user's home on the daemon's own machine, and
+ * on a remote target as a path relative to the target user's home, which
+ * the host resolves, since only that host knows its home. Any other root
+ * must be absolute.
+ */
+export function buildDefaultWorkspaceDir(
+  source: GitWorkspaceSource,
+  target: DefaultDirTarget,
+): string {
+  const configured = target.root ?? DEFAULT_ROOT;
+
+  const parts = {
+    url: source.url,
+    ref: source.ref ?? null,
+    sha: source.sha ?? null,
+  };
+
+  if (configured.startsWith('/')) {
+    return buildWorkspaceDestination({ root: posix.normalize(configured), ...parts });
+  }
+
+  if (configured !== '~' && !configured.startsWith('~/')) {
+    throw new DaemonError(
+      'bad_args',
+      `workspaces root '${configured}' must be an absolute path or start with ~/`,
+    );
+  }
+
+  const normalized = posix.normalize(`./${configured.slice(1)}`);
+  const underHome = normalized === './' || normalized === '.' ? '' : normalized;
+
+  if (underHome === '..' || underHome.startsWith('../')) {
+    throw new DaemonError(
+      'bad_args',
+      `workspaces root '${configured}' must stay under the home directory`,
+    );
+  }
+
+  return target.remote
+    ? buildWorkspaceDestination({ root: underHome, ...parts })
+    : buildWorkspaceDestination({ root: posix.join(target.home, underHome), ...parts });
+}

package/src/daemon/daemon-connection.ts

@@ -926,6 +926,13 @@ export class DaemonConnection {
     }
 
     const data = parsed.data;
+    const cwd = data.cwd;
+
+    if (cwd === undefined && data.workspace?.kind !== 'git') {
+      this.sendErr(req.id, 'bad_args', 'session.spawn requires a cwd');
+
+      return;
+    }
 
     // Every refusal is thrown from the plan, which runs only once a key is
     // claimed: a retry of a held key answers from the key without checking
@@ -972,16 +979,28 @@ export class DaemonConnection {
         ctx.requireWorkspaceTarget(target);
       }
 
+      // A git workspace without a cwd lands where the daemon picks on the
+      // target.
+      const dir =
+        cwd === undefined && data.workspace?.kind === 'git'
+          ? ctx.buildDefaultWorkspaceDir(target, data.workspace)
+          : cwd;
+
+      if (dir === undefined) {
+        throw new DaemonError('bad_args', 'session.spawn requires a cwd');
+      }
+
       // A workspace is materialized at cwd on the target, which only an
-      // absolute path names.
-      if (data.workspace !== undefined && !isAbsolute(data.cwd)) {
+      // absolute path names; a directory the daemon picks on a remote
+      // target is relative to the home there, which the host resolves.
+      if (data.workspace !== undefined && cwd !== undefined && !isAbsolute(cwd)) {
         throw new DaemonError('bad_args', 'a spawn with a workspace requires an absolute cwd');
       }
 
       // A workspace is created, filled, and removed at the one directory
       // the host resolves cwd to, which a dot segment or a control
       // character would make differ from the path as written.
-      if (data.workspace !== undefined && !isPlainWorkspaceDir(data.cwd)) {
+      if (data.workspace !== undefined && !isPlainWorkspaceDir(dir)) {
         throw new DaemonError(
           'bad_args',
           'a spawn with a workspace requires a cwd without . or .. segments or control characters',
@@ -1001,8 +1020,8 @@ export class DaemonConnection {
       }
 
       return {
-        cwd: data.cwd,
-        name: data.name === '' ? basename(data.cwd) : data.name,
+        cwd: dir,
+        name: data.name === '' ? basename(dir) : data.name,
         prompt: data.prompt,
         cols: data.cols,
         rows: data.rows,
@@ -1018,6 +1037,7 @@ export class DaemonConnection {
         },
         target,
         workspace: data.workspace ?? null,
+        autoDir: cwd === undefined,
       };
     };
 

package/src/daemon/daemon-context.ts

@@ -39,6 +39,11 @@ export interface SpawnParams {
   // Where the session's working directory comes from; null runs the
   // session in cwd as it stands.
   readonly workspace: SpawnWorkspaceSource | null;
+
+  // Whether the daemon picked cwd for a git workspace the spawn gave no
+  // directory for, so a held directory moves the spawn to a numbered one
+  // beside it.
+  readonly autoDir: boolean;
 }
 
 interface SessionRecord {
@@ -180,6 +185,14 @@ export interface DaemonContext {
   // one whose provider cannot both transfer an archive and run a command.
   readonly requireWorkspaceTarget: (target: string) => void;
 
+  // The directory a git workspace lands in on a target when the spawn
+  // gives none: absolute on the daemon's own machine, and relative to the
+  // target user's home on a remote target.
+  readonly buildDefaultWorkspaceDir: (
+    target: string,
+    source: Extract<SpawnWorkspaceSource, { kind: 'git' }>,
+  ) => string;
+
   // Throws the refusal for an agent that takes its credential from impd's
   // broker on a target whose provider reaches no broker.
   readonly requireAgentTarget: (agent: AgentID, target: string) => void;

package/src/daemon/daemon.ts

@@ -18,6 +18,7 @@ import { DEFAULT_GIT_TRANSPORTS } from '../shared/default-git-transports';
 import { findDaemonRecord } from '../shared/find-daemon-record';
 import type { MessageID } from '../shared/message-id';
 import { isRecord } from '../shared/report';
+import { resolveHomeDir } from '../shared/resolve-home-dir';
 import type { SessionID } from '../shared/session-id';
 import { toMessageID } from '../shared/to-message-id';
 import { truncateToBytes } from '../shared/truncate-to-bytes';
@@ -34,6 +35,7 @@ import { ANSWER_BYTE_CAP } from './answer-byte-cap';
 import { AttachRegistry } from './attach-registry';
 import { buildAgentList } from './build-agent-list';
 import { buildConfigRevision } from './build-config-revision';
+import { buildDefaultWorkspaceDir } from './build-default-workspace-dir';
 import { buildExecutionTargets } from './build-execution-targets';
 import type { ExecutionTarget } from './build-execution-targets';
 import { buildFleetEvents } from './build-fleet-events';
@@ -178,6 +180,14 @@ export interface DaemonOptions {
   // or the invalid list the config holds, which refuses every git
   // operation; https and ssh when unset.
   readonly gitTransports?: readonly string[] | InvalidGitTransports;
+
+  // The root a git workspace without a directory lands under on any target
+  // without its own, and each target's own root, by target id; the default
+  // root under the target user's home when unset.
+  readonly workspaceRoots?: Readonly<{
+    root: string | null;
+    targetRoots: ReadonlyMap<string, string>;
+  }>;
 }
 
 // The TCP listener's address and the file holding the tokens a handshake
@@ -962,7 +972,9 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
         ? null
         : async (
             host: Readonly<{
-              readyHost: () => Promise<{ readonly host: SessionID; readonly dir: string }>;
+              readyHost: (
+                attempt: number,
+              ) => Promise<{ readonly host: SessionID; readonly dir: string }>;
               removeClaim: (dir: string) => Promise<boolean>;
             }>,
             targetIdentity: string,
@@ -1013,7 +1025,7 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
     id: SessionID,
     source: SpawnWorkspaceSource,
     host: Readonly<{
-      readyHost: () => Promise<{ readonly host: SessionID; readonly dir: string }>;
+      readyHost: (attempt: number) => Promise<{ readonly host: SessionID; readonly dir: string }>;
       removeClaim: (dir: string) => Promise<boolean>;
     }>,
     targetIdentity: string,
@@ -1028,6 +1040,7 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
         dir: p.cwd,
         source,
         inPlace: bound.provider.kind === 'local-pty',
+        autoDir: p.autoDir,
       },
       {
         requireProvider: (capability) => mgr.requireExecution(binding, capability).provider,
@@ -1049,7 +1062,9 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
     materialize:
       | ((
           host: Readonly<{
-            readyHost: () => Promise<{ readonly host: SessionID; readonly dir: string }>;
+            readyHost: (
+              attempt: number,
+            ) => Promise<{ readonly host: SessionID; readonly dir: string }>;
             removeClaim: (dir: string) => Promise<boolean>;
           }>,
           targetIdentity: string,
@@ -1075,6 +1090,7 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
       p.target,
       materialize,
       requireInReach,
+      p.autoDir,
     );
 
     const runtime = runtimes.get(s.id);
@@ -1083,7 +1099,7 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
       runtime.pendingLastUsed = true;
     }
 
-    void store.recordSpawnDir(p.cwd, { target: s.target, targetIdentity: s.targetIdentity });
+    void store.recordSpawnDir(s.cwd, { target: s.target, targetIdentity: s.targetIdentity });
 
     return getDescriptor(mgr, s.id);
   };
@@ -1405,6 +1421,12 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
       mgr.requireExecution({ target, targetIdentity: null }, 'transfer');
       mgr.requireExecution({ target, targetIdentity: null }, 'run');
     },
+    buildDefaultWorkspaceDir: (target, source) =>
+      buildDefaultWorkspaceDir(source, {
+        root: opts.workspaceRoots?.targetRoots.get(target) ?? opts.workspaceRoots?.root ?? null,
+        remote: mgr.requireExecution({ target, targetIdentity: null }, 'run').provider.remote,
+        home: resolveHomeDir(),
+      }),
     requireAgentTarget: (agent, target) => {
       mgr.requireAgentTarget(agent, target);
     },

package/src/daemon/materialize-workspace.ts

@@ -32,6 +32,11 @@ interface MaterializeRequest {
   // Whether the target is the daemon's own host, where a directory outside
   // any git work tree runs in place instead of being materialized.
   readonly inPlace: boolean;
+
+  // Whether the daemon picked the directory, so one that exists or that
+  // another workspace holds moves the claim to the next attempt's
+  // directory instead of refusing the spawn.
+  readonly autoDir?: boolean;
 }
 
 // The host a workspace lands on, and the directory there it is built in.
@@ -48,8 +53,9 @@ interface MaterializeDeps {
   readonly log: (line: string) => void;
 
   // Readies the host on the target the workspace lands on and resolves to
-  // it, once the source has resolved.
-  readonly readyHost: () => Promise<Landing>;
+  // it, once the source has resolved, with the directory of an attempt: the
+  // first is the request's directory, and attempt n appends `-n` to it.
+  readonly readyHost: (attempt: number) => Promise<Landing>;
 
   // Removes the directory this call claimed after a failure, and resolves
   // to whether it did; one it leaves holds what another session needs, or
@@ -254,12 +260,13 @@ async function runMaterialization(
   const repoURL = secret === null ? pinned.repoURL : toRedacted(pinned.repoURL, secret);
   const ref = secret === null || pinned.ref === null ? pinned.ref : toRedacted(pinned.ref, secret);
 
-  const landing = await deps.readyHost();
-
-  updateProgress({ landing });
+  const landing = await claimLanding(request, deps, updateProgress);
 
-  await claimTargetDir(request, deps, landing, updateProgress);
-  await recordPhase(request, deps, updateProgress, 'cloning', { repoURL, ref });
+  await recordPhase(request, deps, updateProgress, 'cloning', {
+    repoURL,
+    ref,
+    ...(request.autoDir === true ? { dir: landing.dir } : {}),
+  });
 
   const clone = await createCleanClone(pinned, join(staging, 'clone'), transports);
 
@@ -401,6 +408,45 @@ async function requireNoURLCredentials(url: string, cwd: string): Promise<void>
   }
 }
 
+// How many directories a spawn whose directory the daemon picked tries
+// before it refuses.
+const AUTO_DIR_ATTEMPTS = 100;
+
+/**
+ * Readies the host and claims the directory the workspace lands in. A
+ * directory the daemon picked moves to the next attempt while the one
+ * before exists or another workspace holds it, so repeated and concurrent
+ * spawns of one repository land side by side; a directory the caller gave
+ * is claimed once.
+ */
+async function claimLanding(
+  request: MaterializeRequest,
+  deps: MaterializeDeps,
+  updateProgress: ProgressTracker,
+): Promise<Landing> {
+  const attempts = request.autoDir === true ? AUTO_DIR_ATTEMPTS : 1;
+
+  for (let attempt = 1; ; attempt += 1) {
+    try {
+      const landing = await deps.readyHost(attempt);
+
+      updateProgress({ landing });
+
+      await claimTargetDir(request, deps, landing, updateProgress);
+
+      return landing;
+    } catch (error) {
+      const held =
+        error instanceof DaemonError &&
+        (error.code === 'workspace_exists' || error.code === 'workspace_overlap');
+
+      if (!held || attempt >= attempts) {
+        throw error;
+      }
+    }
+  }
+}
+
 /**
  * Creates the target directory as the claim on it: `mkdir` without `-p`
  * fails when the directory exists, so a materialization never unpacks over
@@ -412,6 +458,9 @@ async function claimTargetDir(
   landing: Landing,
   updateProgress: ProgressTracker,
 ): Promise<void> {
+  // A directory the daemon picked is reported as it landed.
+  const shown = request.autoDir === true ? landing.dir : request.dir;
+
   const parent = await deps.requireProvider('run').runCommand({
     argv: ['mkdir', '-p', '--', dirname(landing.dir)],
     cwd: '/',
@@ -421,8 +470,8 @@ async function claimTargetDir(
   if (parent.exitCode !== 0) {
     throw new DaemonError(
       'transfer_failed',
-      `cannot create ${dirname(request.dir)} on target '${request.target}': ${parent.stderr.trim()}`,
-      { phase: 'resolving', dir: request.dir },
+      `cannot create ${dirname(shown)} on target '${request.target}': ${parent.stderr.trim()}`,
+      { phase: 'resolving', dir: shown },
     );
   }
 
@@ -430,23 +479,46 @@ async function claimTargetDir(
     .requireProvider('run')
     .runCommand({ argv: ['mkdir', '--', landing.dir], cwd: '/', host: landing.host });
 
+  // A directory that is not there failed for another reason, such as a
+  // parent the command cannot write, which no other attempt would fix.
+  if (claim.exitCode !== 0 && !(await isTargetPathPresent(deps, landing))) {
+    throw new DaemonError(
+      'transfer_failed',
+      `cannot create ${shown} on target '${request.target}': ${claim.stderr.trim()}`,
+      { phase: 'resolving', dir: shown },
+    );
+  }
+
   if (claim.exitCode !== 0) {
     throw new DaemonError(
       'workspace_exists',
-      `${request.dir} already exists on target '${request.target}'; a workspace is materialized only into a directory that does not exist`,
-      { phase: 'resolving', dir: request.dir },
+      `${shown} already exists on target '${request.target}'; a workspace is materialized only into a directory that does not exist`,
+      { phase: 'resolving', dir: shown },
     );
   }
 
   updateProgress({ claimed: true });
 }
 
+// Whether anything, a dangling symlink included, stands at the landing
+// directory's path on its host.
+async function isTargetPathPresent(deps: MaterializeDeps, landing: Landing): Promise<boolean> {
+  const probe = await deps.requireProvider('run').runCommand({
+    argv: ['sh', '-c', '[ -e "$1" ] || [ -L "$1" ]', 'sh', landing.dir],
+    cwd: '/',
+    host: landing.host,
+  });
+
+  return probe.exitCode === 0;
+}
+
 async function recordPhase(
   request: MaterializeRequest,
   deps: MaterializeDeps,
   updateProgress: ProgressTracker,
   phase: MaterializationPhase,
   fields: Readonly<{
+    dir?: string;
     repoURL?: string;
     sha?: string;
     ref?: string | null;

package/src/daemon/sessions.ts

@@ -194,14 +194,18 @@ interface MaterializedSpawn {
 // Builds a spawn's workspace on a target bound to an identity, calling
 // readyHost for the host it lands on once its source resolves and asking
 // canRemoveClaim before a failure removes the directory it claimed, or
-// resolves to null for a directory that runs as it stands.
+// resolves to null for a directory that runs as it stands. readyHost takes
+// the attempt the directory is for: the first is the spawn's directory, and
+// attempt n is that directory with `-n` appended.
 type SpawnMaterializer = (
   host: SpawnHostAccess,
   targetIdentity: string,
 ) => Promise<MaterializedSpawn | null>;
 
 interface SpawnHostAccess {
-  readonly readyHost: () => Promise<{ readonly host: SessionID; readonly dir: string }>;
+  readonly readyHost: (
+    attempt: number,
+  ) => Promise<{ readonly host: SessionID; readonly dir: string }>;
   readonly removeClaim: (dir: string) => Promise<boolean>;
 }
 
@@ -210,7 +214,7 @@ interface SpawnHostAccess {
 interface WorkspaceReservation {
   readonly hostKey: SessionID;
   readonly target: string;
-  readonly dir: string;
+  dir: string;
   resolved: string | null;
 
   // A workspace spawn builds its directory and may remove it on a failure;
@@ -905,6 +909,7 @@ export class SessionManager {
     target = 'local',
     materialize: SpawnMaterializer | null = null,
     requireInReach: () => void = () => {},
+    autoDir = false,
   ): Promise<Session> {
     const adapter = this.findAdapter(agent);
 
@@ -967,9 +972,14 @@ export class SessionManager {
       throw refusal;
     }
 
+    // A directory the daemon picked is checked on the host once per
+    // attempt, so a held one moves the spawn to the next attempt instead of
+    // refusing it.
     if (hostKey !== id) {
       if (materialize === null) {
         this.claimPlainDir(id, hostKey, target, cwd);
+      } else if (autoDir) {
+        this.reservations.set(id, { hostKey, target, dir: cwd, resolved: null, kind: 'workspace' });
       } else {
         this.claimWorkspace(id, hostKey, target, cwd);
       }
@@ -1041,6 +1051,9 @@ export class SessionManager {
       );
     });
 
+    // A spawn whose directory the daemon picked runs in the one it claimed,
+    // as the host resolves it.
+    const dir = autoDir && prepared.root !== null ? prepared.root : cwd;
     const setup = prepared.setup;
     const materialized = prepared.materialized;
     const readied: SpawnReadied = { attemptID: setup.attemptID, root: prepared.root };
@@ -1059,7 +1072,7 @@ export class SessionManager {
         host: hostKey,
         bin: plan.bin,
         args: plan.args,
-        cwd,
+        cwd: dir,
         env: { ...plan.env, ATC_SESSION_ID: id, ATC_SOCKET: socketPath },
         withheldEnv: materialized?.withheldEnv ?? [],
         cols,
@@ -1084,8 +1097,8 @@ export class SessionManager {
 
     const session: Session = {
       id,
-      name,
-      cwd,
+      name: namedBy === 'auto' && dir !== cwd ? posix.basename(dir) : name,
+      cwd: dir,
       kind: 'pty',
       pty,
       state: 'running',
@@ -1095,7 +1108,7 @@ export class SessionManager {
       agent,
       pinned: false,
       lastAttachedAt: Date.now(),
-      repoRoot,
+      repoRoot: dir === cwd ? repoRoot : dir,
       namedBy,
       createdAt: Date.now(),
       parent,
@@ -1306,6 +1319,7 @@ export class SessionManager {
     if (reservation !== undefined) {
       this.requireSeparateWorkspace(id, hostKey, target, dir, [dir, physical], listed.dirs);
 
+      reservation.dir = dir;
       reservation.resolved = physical;
     }
 
@@ -1535,6 +1549,28 @@ export class SessionManager {
     return existing === '/' ? rest || '/' : `${existing}${rest}`;
   }
 
+  // The home directory of the user commands run as on a host, with every
+  // symlink in it resolved.
+  private async resolveHostHome(provider: ExecutionProvider, hostKey: SessionID): Promise<string> {
+    const result = await provider.runCommand({
+      argv: ['sh', '-c', 'cd && pwd -P'],
+      cwd: '/',
+      host: hostKey,
+    });
+
+    const home = result.stdout.replace(/\n$/u, '');
+
+    if (result.exitCode !== 0 || !posix.isAbsolute(home)) {
+      throw new DaemonError(
+        'host_unavailable',
+        `the host of session ${hostKey} cannot resolve its home directory: ${result.stderr.trim()}`,
+        { phase: 'resolving' },
+      );
+    }
+
+    return home;
+  }
+
   // Materializes a spawn's workspace, readying its host once the source
   // resolves, or after the workspace for a directory that runs as it
   // stands, and returns the directory it created, null for one that runs
@@ -1559,15 +1595,26 @@ export class SessionManager {
       root: null,
     };
 
+    const hostHome: { dir: string | null } = { dir: null };
+
     try {
       const materialized = await materialize(
         {
-          readyHost: async () => {
-            readied.setup = await setupHost();
+          readyHost: async (attempt) => {
+            readied.setup ??= await setupHost();
+
+            // A directory the daemon picked on a remote target is relative
+            // to the home there, which only the readied host can resolve.
+            hostHome.dir ??= posix.isAbsolute(dir)
+              ? ''
+              : await this.resolveHostHome(provider, hostKey);
+
+            const base = posix.isAbsolute(dir) ? dir : posix.join(hostHome.dir, dir);
+            const candidate = attempt === 1 ? base : `${base}-${attempt}`;
 
             const landing = this.hasHostLifecycle(target)
-              ? await this.claimHostDir(provider, id, hostKey, target, dir)
-              : await this.resolveHostDir(provider, null, dir);
+              ? await this.claimHostDir(provider, id, hostKey, target, candidate)
+              : await this.resolveHostDir(provider, null, candidate);
 
             readied.root = landing;
 

package/src/mcp/mcp-tools.ts

@@ -44,7 +44,9 @@ const DIRS_INPUT: Readonly<Record<string, unknown>> = z.toJSONSchema(
 const SPAWN_INPUT: Readonly<Record<string, unknown>> = z.toJSONSchema(
   z.strictObject({
     daemon: DAEMON_FIELD,
-    cwd: SPAWN_SCHEMA.shape.cwd.describe('Absolute path of the working directory'),
+    cwd: SPAWN_SCHEMA.shape.cwd.describe(
+      "Absolute path of the working directory. Required, except with a git workspace: omit it there and atc picks a new directory under the target user's home, ~/.local/share/atc/workspaces/<repo>-<ref>-<short sha> unless the config sets another root, adding -2, -3, and so on when that directory exists. The session's cwd in the result holds the path it landed in.",
+    ),
     name: SPAWN_SCHEMA.shape.name.describe('Session name; defaults to the directory basename'),
     prompt: SPAWN_SCHEMA.shape.prompt.describe('First message for the session'),
     agent: SPAWN_SCHEMA.shape.agent.describe(SPAWN_AGENT_DESCRIPTION),
@@ -58,7 +60,7 @@ const SPAWN_INPUT: Readonly<Record<string, unknown>> = z.toJSONSchema(
       'Execution target for the new session, one of the target ids in atc_agents_list. Omit it to run on the default target (spawnDefaults.target). An unknown or unavailable target is refused; atc never runs the session on another target instead.',
     ),
     workspace: SPAWN_SCHEMA.shape.workspace.describe(
-      "Where the session's working directory comes from. Omit it to run the session in cwd as it stands. With it, atc materializes a clean checkout into cwd on the target, which must not exist yet: {kind:'path', path, allowDirty?} checks out the pushed HEAD of a git checkout on the atc host, leaving its uncommitted and untracked changes behind with a warning, or refusing them when allowDirty is 'refuse'; {kind:'git', url, ref or sha, credentialRef?} checks out a branch, tag, or full commit of a repository, with credentialRef {kind:'env', name} naming the atc daemon's environment variable that holds its token. A directory outside git runs in place only on a target on the atc host itself (provider local-pty), with cwd equal to its path. Submodules and Git LFS are refused, and so is a URL that carries a credential.",
+      "Where the session's working directory comes from. Omit it to run the session in cwd as it stands. With it, atc materializes a clean checkout into cwd on the target, which must not exist yet, or for a git source without cwd into a directory atc picks: {kind:'path', path, allowDirty?} checks out the pushed HEAD of a git checkout on the atc host, leaving its uncommitted and untracked changes behind with a warning, or refusing them when allowDirty is 'refuse'; {kind:'git', url, ref or sha, credentialRef?} checks out a branch, tag, or full commit of a repository, with credentialRef {kind:'env', name} naming the atc daemon's environment variable that holds its token. A directory outside git runs in place only on a target on the atc host itself (provider local-pty), with cwd equal to its path. Submodules and Git LFS are refused, and so is a URL that carries a credential.",
     ),
     trustClonedWorkspace: SPAWN_SCHEMA.shape.trustClonedWorkspace.describe(
       "Trust the exact verified clone for this launch. An explicit true or false overrides the configured target trustClonedWorkspace default; omitting both keeps trust off. Requires a workspace source and either stock Claude on the local target, which adds trust for the clone root alone to the user's Claude config, or, on an imp target, a brokered Claude gateway or stock Claude signed in through the broker, each with isolated guest config; other launches are refused. Accepts repository configuration and helpers without changing tool permission mode. Existing guest config is preserved.",

package/src/mcp/require-daemon-features.ts

@@ -20,6 +20,7 @@ const FEATURE_USES: Readonly<Record<DaemonFeature, string>> = {
   'request.principal': 'the target limits of a remote MCP client',
   'spawn.workspace': "atc_session_spawn's workspace",
   'spawn.workspace.trust': "atc_session_spawn's trustClonedWorkspace",
+  'spawn.workspace.autoDir': "atc_session_spawn's git workspace without a cwd",
   sources: 'sources.list and sources.interpret',
   'git.probe': 'git.probe',
   'transport.tcp': 'a TCP connection to the daemon',

package/src/mcp/run-tool.ts

@@ -46,7 +46,7 @@ export function runTool(
 
       const params = {
         ...(typeof args['daemon'] === 'string' ? { daemon: args['daemon'] } : {}),
-        cwd: args['cwd'],
+        ...(args['cwd'] === undefined ? {} : { cwd: args['cwd'] }),
         ...(typeof args['name'] === 'string' ? { name: args['name'] } : {}),
         ...(typeof args['prompt'] === 'string' ? { prompt: args['prompt'] } : {}),
         ...(rawAgent === undefined ? {} : { agent: rawAgent }),
@@ -78,12 +78,20 @@ export function runTool(
       const trustFeatures: readonly DaemonFeature[] =
         args['trustClonedWorkspace'] === undefined ? [] : ['spawn.workspace.trust'];
 
+      // Only a daemon that picks a git workspace's directory takes one
+      // without a cwd.
+      const autoDirFeatures: readonly DaemonFeature[] =
+        args['cwd'] === undefined && args['workspace'] !== undefined
+          ? ['spawn.workspace.autoDir']
+          : [];
+
       const required = [
         ...optionFeatures,
         ...keyFeatures,
         ...targetFeatures,
         ...workspaceFeatures,
         ...trustFeatures,
+        ...autoDirFeatures,
       ];
 
       const ok =

package/src/protocol/daemon-features.ts

@@ -50,6 +50,11 @@ export const DAEMON_FEATURES = [
   // `session.spawn` takes an explicit trust decision for a cloned imp workspace.
   'spawn.workspace.trust',
 
+  // `session.spawn` with a git workspace takes no `cwd`, and the daemon
+  // picks a directory under the target user's home that no other
+  // workspace holds.
+  'spawn.workspace.autoDir',
+
   // `session.forget` exists, and a kill of a session asleep on a target that
   // can destroy its host answers `confirmation_required`.
   'session.forget',

package/src/protocol/request-param-schemas.ts

@@ -151,7 +151,13 @@ export const REQUEST_PARAM_SCHEMAS = {
     rows: buildTerminalSize(24),
   }),
   'session.spawn': z.object({
-    cwd: z.string({ error: 'session.spawn requires a cwd' }).min(1, 'session.spawn requires a cwd'),
+    // The working directory on the target. A spawn with a git workspace may
+    // leave it out, and the daemon then picks a directory under the target
+    // user's home; every other spawn requires it.
+    cwd: z
+      .string({ error: 'session.spawn requires a cwd' })
+      .min(1, 'session.spawn requires a cwd')
+      .optional(),
     name: buildDefaultedString(''),
     prompt: buildDefaultedString(''),
     cols: buildTerminalSize(80),

package/src/{client → shared}/build-workspace-destination.ts

@@ -1,5 +1,6 @@
 interface DestinationParts {
-  // The root the checkout lands under, absolute on its target.
+  // The root the checkout lands under: absolute on its target, or relative
+  // to the target user's home, where an empty root is the home itself.
   readonly root: string;
 
   // The repository URL the checkout comes from, as the daemon resolved it.
@@ -7,15 +8,18 @@ interface DestinationParts {
 
   // The branch or tag the commit was chosen by, or null for a bare commit.
   readonly ref: string | null;
-  readonly sha: string;
+
+  // The commit checked out, or null when only the ref picks it.
+  readonly sha: string | null;
 }
 
 /**
  * The default directory a git workspace lands in: `<repo>-<ref>-<short
- * sha>` under the root, with the ref left out for a bare commit. The repo
- * is the URL's last path segment without `.git`, and each part keeps only
- * `[A-Za-z0-9._-]`, with `/` turned into `-`, so the name is one path
- * segment on any target.
+ * sha>` under the root, with the ref left out for a bare commit and the
+ * short sha for a ref alone. The repo is the URL's last path segment
+ * without `.git`, and each part keeps only `[A-Za-z0-9._-]`, with `/`
+ * turned into `-`, so the name is one path segment on any target; a name
+ * with nothing left is `workspace`.
  */
 export function buildWorkspaceDestination(parts: DestinationParts): string {
   const repo =
@@ -25,12 +29,19 @@ export function buildWorkspaceDestination(parts: DestinationParts): string {
       .at(-1)
       ?.replace(/\.git$/u, '') ?? '';
 
-  const name = [repo, ...(parts.ref === null ? [] : [parts.ref]), parts.sha.slice(0, 7)]
+  const name = [
+    repo,
+    ...(parts.ref === null ? [] : [parts.ref]),
+    ...(parts.sha === null ? [] : [parts.sha.slice(0, 7)]),
+  ]
     .map((part) => toSafeSegment(part))
     .filter((part) => part !== '')
     .join('-');
 
-  return `${parts.root.replace(/\/+$/u, '')}/${name}`;
+  const segment = name === '' ? 'workspace' : name;
+  const root = parts.root.replace(/\/+$/u, '');
+
+  return parts.root === '' ? segment : `${root}/${segment}`;
 }
 
 function toSafeSegment(part: string): string {

package/src/store/state-store.ts

@@ -939,6 +939,7 @@ export class StateStore {
       .updateTable('workspace_materialization')
       .set({
         phase: fields.phase,
+        ...(fields.dir === undefined ? {} : { dir: fields.dir }),
         ...(fields.repoURL === undefined ? {} : { repo_url: fields.repoURL }),
         ...(fields.sha === undefined ? {} : { sha: fields.sha }),
         ...(fields.ref === undefined ? {} : { ref: fields.ref }),

package/src/store/workspace-materialization.ts

@@ -50,6 +50,10 @@ export interface WorkspaceMaterialization {
 // The fields a materialization rewrites as it moves through its phases.
 export interface MaterializationUpdate {
   readonly phase: MaterializationPhase;
+
+  // The directory the workspace landed in, once a directory the daemon
+  // picked is claimed.
+  readonly dir?: string;
   readonly repoURL?: string;
   readonly sha?: string;
   readonly ref?: string | null;