@zgeoff/atc 2.26.1 → 2.26.3

package/package.json

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

package/src/client/pick-refusal-step.ts

@@ -3,6 +3,7 @@ type RefusalStep = 'confirm' | 'destination' | 'ref' | 'source';
 
 const REFUSAL_STEPS: ReadonlyMap<string, RefusalStep> = new Map<string, RefusalStep>([
   ['workspace_exists', 'destination'],
+  ['workspace_overlap', 'destination'],
   ['ref_not_found', 'ref'],
   ['invalid_git_url', 'source'],
   ['credential_in_url', 'source'],

package/src/daemon/daemon-connection.ts

@@ -976,6 +976,16 @@ export class DaemonConnection {
         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)) {
+        throw new DaemonError(
+          'bad_args',
+          'a spawn with a workspace requires a cwd without . or .. segments or control characters',
+        );
+      }
+
       let parent: SessionID | null = null;
 
       if (data.parent !== undefined) {
@@ -1791,3 +1801,12 @@ function findEventSession(event: EventMsg): SessionID | null {
 
   return null;
 }
+
+// oxlint-disable-next-line no-control-regex -- control characters are what a workspace cwd is refused for
+const CONTROL_CHARACTER = /[\u0000-\u001F\u007F]/u;
+
+function isPlainWorkspaceDir(dir: string): boolean {
+  return (
+    !CONTROL_CHARACTER.test(dir) && !dir.split('/').some((part) => part === '.' || part === '..')
+  );
+}

package/src/daemon/daemon.ts

@@ -938,9 +938,9 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
     });
   };
 
-  // A spawn with a workspace source materializes it first, and the session
-  // registers only once its workspace is ready, so no session ever lists
-  // over a half-built checkout. A spawn that throws once its process has
+  // A spawn with a workspace source materializes it once every refusal has
+  // passed and its host is ready, and the session registers only once its
+  // workspace is ready, so no session ever lists over a half-built checkout. A spawn that throws once its process has
   // started takes the session back before it throws, so a failed start
   // leaves nothing running and a keyed retry spawns once. When taking it
   // back fails too, the session may still stand, and the throw says so.
@@ -949,17 +949,42 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
     id: SessionID,
     requireInReach: () => void = () => {},
   ): Promise<Readonly<Record<string, unknown>>> => {
-    const prepared =
-      p.workspace === null ? null : await materializeSpawnWorkspace(p, id, p.workspace);
+    const source = p.workspace;
+    let warnings: readonly string[] = [];
+
+    const materialize =
+      source === null
+        ? null
+        : async (
+            host: Readonly<{
+              readyHost: () => Promise<{ readonly host: SessionID; readonly dir: string }>;
+              removeClaim: (dir: string) => Promise<boolean>;
+            }>,
+            targetIdentity: string,
+          ) => {
+            const prepared = await materializeSpawnWorkspace(p, id, source, host, targetIdentity);
+
+            if (prepared.kind !== 'ready') {
+              return null;
+            }
+
+            warnings = prepared.warnings;
 
-    const materialized = prepared?.kind === 'ready' ? prepared : null;
-    const warnings = materialized === null ? [] : materialized.warnings;
+            return prepared;
+          };
 
     try {
-      const session = await startSpawnedSession(p, id, materialized, requireInReach);
+      const session = await startSpawnedSession(p, id, materialize, requireInReach);
 
       return warnings.length === 0 ? { session } : { session, warnings };
     } catch (error) {
+      // A failed spawn gives back the workspace directory it reserved,
+      // unless what it did may still stand: its key then stays held as
+      // outcome_unknown, and so does its directory.
+      if (!(error instanceof EffectRemainsError)) {
+        mgr.releaseWorkspace(id);
+      }
+
       try {
         await mgr.removeFailedSpawn(id);
       } catch (cleanupError) {
@@ -975,16 +1000,21 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
     }
   };
 
-  // Materializes a spawn's workspace on its target. The target's identity
-  // binds when the materialization starts, and every provider call after
-  // passes the execution gate against that binding.
+  // Materializes a spawn's workspace on the host its spawn readies once the
+  // source resolves, under the target identity the spawn bound, and every
+  // provider call passes the execution gate against that binding.
   const materializeSpawnWorkspace = (
     p: SpawnParams,
     id: SessionID,
     source: SpawnWorkspaceSource,
+    host: Readonly<{
+      readyHost: () => Promise<{ readonly host: SessionID; readonly dir: string }>;
+      removeClaim: (dir: string) => Promise<boolean>;
+    }>,
+    targetIdentity: string,
   ) => {
-    const bound = mgr.requireExecution({ target: p.target, targetIdentity: null }, 'run');
-    const binding = { target: p.target, targetIdentity: bound.identity };
+    const binding = { target: p.target, targetIdentity };
+    const bound = mgr.requireExecution(binding, 'run');
 
     return materializeWorkspace(
       {
@@ -1000,6 +1030,8 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
         log: (line) => {
           mgr.log(line);
         },
+        readyHost: host.readyHost,
+        removeClaim: host.removeClaim,
         stagingRoot: tmpdir(),
         gitTransports,
       },
@@ -1009,10 +1041,18 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
   const startSpawnedSession = async (
     p: SpawnParams,
     id: SessionID,
-    materialized: Readonly<{
-      workspace: SessionWorkspace;
-      withheldEnv: readonly string[];
-    }> | null,
+    materialize:
+      | ((
+          host: Readonly<{
+            readyHost: () => Promise<{ readonly host: SessionID; readonly dir: string }>;
+            removeClaim: (dir: string) => Promise<boolean>;
+          }>,
+          targetIdentity: string,
+        ) => Promise<Readonly<{
+          workspace: SessionWorkspace;
+          withheldEnv: readonly string[];
+        }> | null>)
+      | null,
     requireInReach: () => void,
   ): Promise<SessionDescriptor> => {
     const s = await mgr.spawn(
@@ -1028,7 +1068,7 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
       p.overrides,
       id,
       p.target,
-      materialized,
+      materialize,
       requireInReach,
     );
 

package/src/daemon/imp-client-port.ts

@@ -248,16 +248,8 @@ export class ImpClientPort implements ImpPort {
   };
 
   // oxlint-disable-next-line prefer-readonly-parameter-types -- the command's input bytes have no readonly form
-  readonly runCommand = async (name: string, command: ImpCommand): Promise<ImpCommandResult> => {
-    const result = await this.tryCall((client) =>
-      client.run(name, command.argv, {
-        ...(command.cwd === undefined ? {} : { cwd: command.cwd }),
-        ...(command.stdin === undefined ? {} : { stdin: command.stdin }),
-      }),
-    );
-
-    return { code: result.code, stdout: result.stdout, stderr: result.stderr };
-  };
+  readonly runCommand = (name: string, command: ImpCommand): Promise<ImpCommandResult> =>
+    this.tryCall((client) => runCommandInChunks(client, name, command));
 
   readonly openReverseForward = (
     name: string,
@@ -425,6 +417,51 @@ async function waitForSessionOutcome(outcome: Promise<ExecOutcome>): Promise<Imp
   return ended;
 }
 
+// impd takes no WebSocket message over its size limit and closes the exec
+// when one arrives, so a command's input goes over in pieces well below it.
+const STDIN_CHUNK_BYTES = 1024 * 1024;
+
+// Runs a command with its input sent a piece at a time. A command that ends
+// before it takes all its input answers with its own exit, or with the
+// failure that ended it, never with the refused write.
+async function runCommandInChunks(
+  client: ImpClient,
+  name: string,
+
+  // oxlint-disable-next-line prefer-readonly-parameter-types -- the command's input bytes have no readonly form
+  command: ImpCommand,
+): Promise<ImpCommandResult> {
+  const options = command.cwd === undefined ? {} : { cwd: command.cwd };
+
+  const handle = await client.openExec(name, command.argv, options);
+
+  const output = Promise.all([
+    new Response(handle.stdout).bytes(),
+    new Response(handle.stderr).bytes(),
+  ]);
+
+  try {
+    const stdin = command.stdin ?? new Uint8Array(0);
+
+    for (let at = 0; at < stdin.byteLength; at += STDIN_CHUNK_BYTES) {
+      await handle.write(stdin.subarray(at, at + STDIN_CHUNK_BYTES));
+    }
+
+    await handle.closeStdin();
+  } catch {
+    // A write fails once the exec has ended, and the exit holds why: the
+    // command's own exit, or the failure that ended it, which rethrows
+    // here. Closing first ends an exec the failed write left running.
+    handle.close();
+
+    await handle.exit;
+  }
+
+  const [exit, [stdout, stderr]] = await Promise.all([handle.exit, output]);
+
+  return { code: exit.code, stdout, stderr };
+}
+
 // oxlint-disable-next-line prefer-readonly-parameter-types -- a promise is a live handle
 async function waitForListening(listening: Promise<unknown>): Promise<void> {
   await listening;

package/src/daemon/imp-provider.ts

@@ -4,6 +4,7 @@ import { isCompiledBinary } from '../shared/is-compiled-binary';
 import type { BrokerAuthHost } from './broker-auth-host';
 import { buildImpName } from './build-imp-name';
 import { buildTarArchive } from './build-tar-archive';
+import { EffectRemainsError } from './effect-remains-error';
 import type {
   CommandResult,
   CommandSpec,
@@ -219,9 +220,18 @@ export class ImpProvider implements ExecutionProvider {
 
       await this.setupGuest(name, request.installATC === true);
     } catch (error) {
-      await this.tryUndoPrepare(name, label, created, leased);
+      const undone = await this.tryUndoPrepare(name, label, created, leased);
 
-      throw toHostRefusal(error, name);
+      const refusal = toHostRefusal(error, name);
+
+      if (!undone) {
+        throw new EffectRemainsError(
+          `imp ${name} failed to ready and destroying the imp it created failed too`,
+          { cause: refusal },
+        );
+      }
+
+      throw refusal;
     }
 
     const host = this.hosts.get(request.host) ?? {
@@ -405,20 +415,29 @@ export class ImpProvider implements ExecutionProvider {
   // Takes back what a failed prepare left: an imp it created is destroyed,
   // which ends the lease on it too, since no session was ever listed on it;
   // on an imp that existed before, only the lease this prepare took is
-  // given back, and the imp itself stays.
+  // given back, and the imp itself stays. Resolves to false when an imp it
+  // created may still stand; a lease left behind runs out on its own.
   private async tryUndoPrepare(
     name: string,
     label: string,
     created: boolean,
     leased: boolean,
-  ): Promise<void> {
-    try {
-      if (created) {
+  ): Promise<boolean> {
+    if (created) {
+      try {
         await this.port.destroyImp(name);
-      } else if (leased) {
-        await this.port.releaseLease(name, label);
+
+        return true;
+      } catch (error) {
+        return error instanceof ImpPortError && error.code === 'NOT_FOUND';
       }
-    } catch {}
+    }
+
+    if (leased) {
+      await this.port.releaseLease(name, label).catch(() => false);
+    }
+
+    return true;
   }
 
   // Readies the folder the harnesses' report sockets live in, and copies

package/src/daemon/materialize-workspace.ts

@@ -17,6 +17,7 @@ import { resolveGitURL } from '../workspace/resolve-git-url';
 import { resolvePathSource } from '../workspace/resolve-path-source';
 import { runGit } from '../workspace/run-git';
 import { sanitizeWorkspaceClone } from '../workspace/sanitize-workspace-clone';
+import { EffectRemainsError } from './effect-remains-error';
 import type { ExecutionProvider } from './execution-provider';
 import { requireGitTransports } from './require-git-transports';
 
@@ -33,6 +34,12 @@ interface MaterializeRequest {
   readonly inPlace: boolean;
 }
 
+// The host a workspace lands on, and the directory there it is built in.
+interface Landing {
+  readonly host: string;
+  readonly dir: string;
+}
+
 interface MaterializeDeps {
   // The target's provider for one operation, after the execution gate
   // passes it; throws the gate's refusal otherwise.
@@ -40,6 +47,15 @@ interface MaterializeDeps {
   readonly store: Pick<StateStore, 'createMaterialization' | 'updateMaterialization'>;
   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>;
+
+  // Removes the directory this call claimed after a failure, and resolves
+  // to whether it did; one it leaves holds what another session needs, or
+  // no longer resolves to itself.
+  readonly removeClaim: (dir: string) => Promise<boolean>;
+
   // The directory on the daemon's host that holds each clone's staging
   // directory while the workspace is built.
   readonly stagingRoot: string;
@@ -63,6 +79,10 @@ interface ReadyWorkspace {
 interface MaterializationProgress {
   phase: MaterializationPhase;
 
+  // The host the workspace lands on and its directory there, once the
+  // host is ready.
+  landing: Landing | null;
+
   // Whether this call created the target directory, so a failure removes
   // only a directory it made.
   claimed: boolean;
@@ -113,7 +133,7 @@ export async function materializeWorkspace(
 
   const secret = findCredentialSecret(source);
   const withheldEnv = buildWithheldEnv(source);
-  const progress: MaterializationProgress = { phase: 'resolving', claimed: false };
+  const progress: MaterializationProgress = { phase: 'resolving', landing: null, claimed: false };
 
   const updateProgress = (update: Readonly<Partial<MaterializationProgress>>) => {
     Object.assign(progress, update);
@@ -145,14 +165,28 @@ export async function materializeWorkspace(
   } catch (error) {
     const refusal = toScrubbedRefusal(error, progress.phase, secret);
 
-    await tryRemoveClaimedDir(request, deps, progress, secret);
-    await tryUpdateFailed(request, deps, refusal.code);
+    // A failure that may have left an effect standing, such as a host the
+    // spawn could not take back, reaches the caller as it is, so a keyed
+    // spawn keeps its key as outcome_unknown.
+    const remains = error instanceof EffectRemainsError;
+    const code = remains ? 'outcome_unknown' : refusal.code;
+
+    const left = await tryRemoveClaimedDir(request, deps, progress, secret);
+
+    await tryUpdateFailed(request, deps, code);
 
     deps.log(
-      `atc: workspace for session ${request.sessionID} failed while ${progress.phase}: ${refusal.code}: ${refusal.message}`,
+      `atc: workspace for session ${request.sessionID} failed while ${progress.phase}: ${code}: ${refusal.message}`,
     );
 
-    throw refusal;
+    if (remains) {
+      throw error;
+    }
+
+    // A directory the failure left is reported, so the caller can remove it.
+    throw left === null
+      ? refusal
+      : new DaemonError(refusal.code, refusal.message, { ...refusal.data, leftDir: left });
   }
 }
 
@@ -220,7 +254,11 @@ 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);
 
-  await claimTargetDir(request, deps, updateProgress);
+  const landing = await deps.readyHost();
+
+  updateProgress({ landing });
+
+  await claimTargetDir(request, deps, landing, updateProgress);
   await recordPhase(request, deps, updateProgress, 'cloning', { repoURL, ref });
 
   const clone = await createCleanClone(pinned, join(staging, 'clone'), transports);
@@ -231,13 +269,15 @@ async function runMaterialization(
   await recordPhase(request, deps, updateProgress, 'transferring', { sha: clone.sha });
 
   try {
-    await deps.requireProvider('transfer').transferArchive(clone.archive, request.dir);
+    await deps
+      .requireProvider('transfer')
+      .transferArchive(clone.archive, landing.dir, landing.host);
   } catch (error) {
     throw toDaemonError(error, 'transfer_failed', 'transferring');
   }
 
   await recordPhase(request, deps, updateProgress, 'verifying', {});
-  await verifyTargetHead(request, deps, clone.sha);
+  await verifyTargetHead(request, deps, landing, clone.sha);
 
   const materializedAt = Date.now();
 
@@ -306,6 +346,16 @@ async function resolveSource(
     };
   }
 
+  // A credential the clone would refuse is refused here, before any host
+  // is readied for it.
+  if (source.credentialRef !== undefined && findCredentialSecret(source) === null) {
+    throw new DaemonError(
+      'credential_missing',
+      'the credential environment variable is unset or empty',
+      { phase: 'resolving' },
+    );
+  }
+
   // The clone fetches the URL it records, so the spawn API's `owner/repo`
   // shorthand reaches the repository it expands to.
   const resolved = await resolveGitURL(expandGitShorthand(source.url), staging, transports);
@@ -359,11 +409,14 @@ async function requireNoURLCredentials(url: string, cwd: string): Promise<void>
 async function claimTargetDir(
   request: MaterializeRequest,
   deps: MaterializeDeps,
+  landing: Landing,
   updateProgress: ProgressTracker,
 ): Promise<void> {
-  const parent = await deps
-    .requireProvider('run')
-    .runCommand({ argv: ['mkdir', '-p', '--', dirname(request.dir)], cwd: '/' });
+  const parent = await deps.requireProvider('run').runCommand({
+    argv: ['mkdir', '-p', '--', dirname(landing.dir)],
+    cwd: '/',
+    host: landing.host,
+  });
 
   if (parent.exitCode !== 0) {
     throw new DaemonError(
@@ -375,7 +428,7 @@ async function claimTargetDir(
 
   const claim = await deps
     .requireProvider('run')
-    .runCommand({ argv: ['mkdir', '--', request.dir], cwd: '/' });
+    .runCommand({ argv: ['mkdir', '--', landing.dir], cwd: '/', host: landing.host });
 
   if (claim.exitCode !== 0) {
     throw new DaemonError(
@@ -487,11 +540,12 @@ const STATUS_ARGV = [
 async function verifyTargetHead(
   request: MaterializeRequest,
   deps: MaterializeDeps,
+  landing: Landing,
   sha: string,
 ): Promise<void> {
   const head = await deps
     .requireProvider('run')
-    .runCommand({ argv: [...VERIFY_ENV, ...VERIFY_ARGV], cwd: request.dir });
+    .runCommand({ argv: [...VERIFY_ENV, ...VERIFY_ARGV], cwd: landing.dir, host: landing.host });
 
   const actual = head.exitCode === 0 ? head.stdout.trim() : null;
 
@@ -505,7 +559,7 @@ async function verifyTargetHead(
 
   const status = await deps
     .requireProvider('run')
-    .runCommand({ argv: [...VERIFY_ENV, ...STATUS_ARGV], cwd: request.dir });
+    .runCommand({ argv: [...VERIFY_ENV, ...STATUS_ARGV], cwd: landing.dir, host: landing.host });
 
   const changed = status.stdout.split('\n').filter((line) => line !== '');
 
@@ -550,35 +604,43 @@ function toRedacted(text: string, secret: string): string {
 
 /**
  * Removes the target directory after a failure, when this call created it,
- * so a failed materialization leaves no partial checkout behind. A removal
- * that fails is logged; the directory then stays and blocks the next
- * materialization into it with `workspace_exists`.
+ * so a failed materialization leaves no partial checkout behind. Resolves
+ * to the directory when it stays, logged with the reason: one another
+ * session's directory lies inside, one that no longer resolves to itself,
+ * or one whose removal failed. It then blocks the next materialization
+ * into it with `workspace_exists` until an operator removes it.
  */
 async function tryRemoveClaimedDir(
   request: MaterializeRequest,
   deps: MaterializeDeps,
   progress: Readonly<MaterializationProgress>,
   secret: string | null,
-): Promise<void> {
-  if (!progress.claimed) {
-    return;
+): Promise<string | null> {
+  if (!progress.claimed || progress.landing === null) {
+    return null;
   }
 
+  const dir = progress.landing.dir;
+
   try {
-    const removed = await deps
-      .requireProvider('run')
-      .runCommand({ argv: ['rm', '-rf', '--', request.dir], cwd: '/' });
+    const removed = await deps.removeClaim(dir);
 
-    if (removed.exitCode !== 0) {
-      throw new Error(removed.stderr.trim());
+    if (removed) {
+      return null;
     }
+
+    deps.log(
+      `atc: left ${dir} on target '${request.target}' after its workspace for session ${request.sessionID} failed: another session's directory lies inside it, or it no longer resolves to itself; remove it by hand`,
+    );
   } catch (error) {
     const reason = toScrubbedRefusal(error, progress.phase, secret).message;
 
     deps.log(
-      `atc: cannot remove ${request.dir} after its workspace for session ${request.sessionID} failed: ${reason}`,
+      `atc: left ${dir} on target '${request.target}' after its workspace for session ${request.sessionID} failed, since removing it failed: ${reason}; remove it by hand`,
     );
   }
+
+  return dir;
 }
 
 async function tryUpdateFailed(

package/src/daemon/sessions.ts

@@ -1,4 +1,5 @@
 import { writeFileSync } from 'node:fs';
+import { posix } from 'node:path';
 import type {
   AgentAdapter,
   GuestPaths,
@@ -33,6 +34,7 @@ import { buildSessionLifecycle } from './build-session-lifecycle';
 import type { SessionLifecycle } from './build-session-lifecycle';
 import { buildTarArchive } from './build-tar-archive';
 import { buildTargetIdentity } from './build-target-identity';
+import { EffectRemainsError } from './effect-remains-error';
 import type {
   ExecutionCapability,
   ExecutionProvider,
@@ -185,6 +187,54 @@ interface MaterializedSpawn {
   readonly withheldEnv: readonly string[];
 }
 
+// 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.
+type SpawnMaterializer = (
+  host: SpawnHostAccess,
+  targetIdentity: string,
+) => Promise<MaterializedSpawn | null>;
+
+interface SpawnHostAccess {
+  readonly readyHost: () => Promise<{ readonly host: SessionID; readonly dir: string }>;
+  readonly removeClaim: (dir: string) => Promise<boolean>;
+}
+
+// A workspace directory a spawn on a shared host holds, as the spawn gave
+// it and as the host resolves it once checked there.
+interface WorkspaceReservation {
+  readonly hostKey: SessionID;
+  readonly target: string;
+  readonly dir: string;
+  resolved: string | null;
+
+  // A workspace spawn builds its directory and may remove it on a failure;
+  // a plain spawn only starts in its directory, which another plain spawn
+  // may share.
+  readonly kind: 'workspace' | 'plain';
+}
+
+// Prints a directory with every symlink in it resolved: its nearest
+// existing directory as the host resolves it and a newline, which keeps a
+// name that ends in newlines whole, then a NUL and the rest of the path as
+// given.
+const RESOLVE_DIR_SCRIPT = `p=$1; s=; while [ ! -d "$p" ]; do s=/\${p##*/}$s; p=\${p%/*}; [ -n "$p" ] || p=/; done; cd -P -- "$p" && pwd -P && printf '\\0%s' "$s"`;
+
+// Removes a directory only while it still resolves to itself: it enters
+// the directory, compares where it landed with the path it was given, and
+// removes the contents from inside it, so no symlink changed on the way is
+// followed, then the directory itself, which is empty by then.
+const REMOVE_DIR_SCRIPT =
+  'cd -P -- "$1" || exit 3; [ "$(pwd -P; printf x)" = "$2" ] || exit 4; find . -mindepth 1 -maxdepth 1 -exec rm -rf -- {} + || exit 5; cd / && rmdir -- "$1"';
+
+// A readied host's harness plan, and the auth attempt that provisioned the
+// host, if one did.
+interface HarnessSetup {
+  readonly plan: HarnessPlan;
+  readonly attemptID: string | null;
+}
+
 // The identity of the implicit `local` target, which a fleet row without a
 // stored identity ran on.
 const LOCAL_TARGET_IDENTITY = buildTargetIdentity('local-pty', {});
@@ -283,6 +333,14 @@ export class SessionManager {
   // so a host with a launch in flight is never idle.
   private readonly readying = new Map<SessionID, number>();
 
+  // The workspace directory each spawn on a shared host holds from its
+  // overlap check until its session lists or its spawn fails, by spawn id.
+  private readonly reservations = new Map<SessionID, WorkspaceReservation>();
+
+  // The shared hosts with a workspace rollback removing a directory now,
+  // each with how many removals run there.
+  private readonly removals = new Map<string, number>();
+
   // Sessions dropped from the list on purpose whose rows the next fleet
   // write deletes; each stays here until a write carrying it lands.
   private readonly removedIDs = new Set<SessionID>();
@@ -805,9 +863,11 @@ export class SessionManager {
   // the new process runs with, and the session keeps them for every revive.
   // id is minted here unless the caller minted it ahead of the spawn. target
   // is the execution target the harness runs on; one this daemon cannot use
-  // refuses the spawn before anything starts. materialized holds what cwd
-  // was materialized from, when it was, and the variables the session's
-  // harnesses go without.
+  // refuses the spawn before anything starts. materialize builds cwd on the
+  // host once every refusal has passed and the host is ready, and returns
+  // what cwd was materialized from, when it was, and the variables the
+  // session's harnesses go without; a failure there takes back the host the
+  // spawn readied, unless it is a parent's.
   async spawn(
     cwd: string,
     name: string,
@@ -821,7 +881,7 @@ export class SessionManager {
     overrides: SpawnOverrides = {},
     id: SessionID = mintSessionID(),
     target = 'local',
-    materialized: MaterializedSpawn | null = null,
+    materialize: SpawnMaterializer | null = null,
     requireInReach: () => void = () => {},
   ): Promise<Session> {
     const adapter = this.findAdapter(agent);
@@ -853,16 +913,52 @@ export class SessionManager {
             targetIdentity: execution.identity,
           };
 
-    const setup = await this.setupHarness(
-      adapter,
-      provider,
-      id,
-      hostKey,
-      target,
-      { prompt, resume, ...overrides },
-      authSetup,
-    );
+    const refusal = adapter.findSpawnRefusal?.() ?? null;
+
+    if (refusal !== null) {
+      throw refusal;
+    }
+
+    if (hostKey !== id) {
+      if (materialize === null) {
+        this.claimPlainDir(id, hostKey, target, cwd);
+      } else {
+        this.claimWorkspace(id, hostKey, target, cwd);
+      }
+    }
+
+    const setupHost = () =>
+      this.setupHarnessOnHost(
+        adapter,
+        provider,
+        id,
+        hostKey,
+        target,
+        { prompt, resume, ...overrides },
+        authSetup,
+      );
 
+    // The host stays readying until its workspace is in place, so nothing
+    // gives its lease back or puts it to sleep in between.
+    const prepared = await this.withHostReadying(hostKey, async () => {
+      if (materialize === null) {
+        return { setup: await setupHost(), materialized: null };
+      }
+
+      return this.materializeOnSpawnHost(
+        provider,
+        id,
+        hostKey,
+        target,
+        cwd,
+        execution.identity,
+        materialize,
+        setupHost,
+      );
+    });
+
+    const setup = prepared.setup;
+    const materialized = prepared.materialized;
     const plan = setup.plan;
 
     // The caller's check runs again once the host is ready, before the
@@ -933,6 +1029,7 @@ export class SessionManager {
 
     this.attachHarness(session, pty, this.hasHostLifecycle(target));
     this.sessions.push(session);
+    this.releaseWorkspace(id);
     void this.tryWriteFleet(session.id);
     this.writeStatus();
     this.onEvent('added', session);
@@ -990,7 +1087,8 @@ export class SessionManager {
   }
 
   // A sub-session joins its parent's host only under the binding that host
-  // holds: both without runtime auth, or both bound to the same hash.
+  // holds: both without runtime auth, or both bound to the same hash, and
+  // then only while that binding is ready.
   private async requireSharedBinding(
     hostKey: SessionID,
     binding: AuthBinding | null,
@@ -1004,6 +1102,14 @@ export class SessionManager {
     }
 
     if (held !== null && binding !== null && held.bindingHash === binding.hash) {
+      if (held.state !== 'ready') {
+        throw new DaemonError(
+          'auth_blocked',
+          `the runtime auth of host ${hostKey} is ${held.state}; rebind it to launch again`,
+          { host: hostKey, state: held.state },
+        );
+      }
+
       return;
     }
 
@@ -1014,6 +1120,375 @@ export class SessionManager {
     );
   }
 
+  /**
+   * Gives back the workspace directory a spawn reserved on a shared host.
+   * The spawn's session listing gives it back, and so does a failed spawn,
+   * except one whose effects may still stand, whose directory stays
+   * reserved so no other workspace lands in or around what it left.
+   */
+  releaseWorkspace(id: SessionID): void {
+    this.reservations.delete(id);
+  }
+
+  // Claims a workspace's directory on a shared host, refusing one inside
+  // or around the directory of a session listed there or of another spawn's
+  // reservation. The check and the reservation run in one turn, so of two
+  // concurrent spawns at most one passes.
+  private claimWorkspace(id: SessionID, hostKey: SessionID, target: string, dir: string): void {
+    const listed = this.sessions
+      .filter((s) => s.hostKey === hostKey && s.target === target && posix.isAbsolute(s.cwd))
+      .map((s) => [s.id, s.cwd] as const);
+
+    this.requireSeparateWorkspace(id, hostKey, target, dir, [dir], listed);
+    this.reservations.set(id, { hostKey, target, dir, resolved: null, kind: 'workspace' });
+  }
+
+  // Holds a plain spawn's directory on a shared host until the session
+  // lists, refusing one inside or around a directory a workspace spawn is
+  // still building there: that spawn's rollback could remove it. While a
+  // rollback removes a directory on the host, every plain spawn there is
+  // refused, since its directory may reach the one going through a
+  // symlink no check has resolved yet. Plain spawns share directories
+  // freely, and a rollback resolves each held plain directory on the host
+  // and keeps a directory that holds one.
+  private claimPlainDir(id: SessionID, hostKey: SessionID, target: string, dir: string): void {
+    if ((this.removals.get(buildHostSlot(hostKey, target)) ?? 0) > 0) {
+      throw new DaemonError(
+        'workspace_overlap',
+        `a failed workspace spawn is removing its directory on the host of session ${hostKey}; spawn again once it is done`,
+        { phase: 'resolving', dir, session: hostKey },
+      );
+    }
+
+    for (const [other, r] of this.reservations) {
+      if (!posix.isAbsolute(dir)) {
+        break;
+      }
+
+      if (
+        other !== id &&
+        r.kind === 'workspace' &&
+        r.hostKey === hostKey &&
+        r.target === target &&
+        [r.dir, r.resolved ?? r.dir].some((held) => isPathOverlapping(dir, held))
+      ) {
+        throw new DaemonError(
+          'workspace_overlap',
+          `${dir} overlaps ${r.dir}, where session ${other} is still building its workspace on the same host`,
+          { phase: 'resolving', dir, session: other },
+        );
+      }
+    }
+
+    this.reservations.set(id, { hostKey, target, dir, resolved: null, kind: 'plain' });
+  }
+
+  // The directory a spawn's workspace lands in, as the readied host
+  // resolves it: every later step creates, fills, and removes this
+  // physical path, never the requested one. On a shared host the spawn's
+  // claim is checked again against every directory as the host resolves
+  // it, and records the physical path, in the turn after the last wait,
+  // with the sessions listed then.
+  private async claimHostDir(
+    provider: ExecutionProvider,
+    id: SessionID,
+    hostKey: SessionID,
+    target: string,
+    dir: string,
+  ): Promise<string> {
+    const before = this.collectHostSessionIDs(hostKey, target);
+
+    const physical = await this.resolveHostDir(provider, hostKey, dir);
+    const listed = await this.resolveListedDirs(provider, hostKey, target);
+
+    if (this.collectHostSessionIDs(hostKey, target) !== before) {
+      return this.claimHostDir(provider, id, hostKey, target, dir);
+    }
+
+    const reservation = this.reservations.get(id);
+
+    if (reservation !== undefined) {
+      this.requireSeparateWorkspace(id, hostKey, target, dir, [dir, physical], listed.dirs);
+
+      reservation.resolved = physical;
+    }
+
+    return physical;
+  }
+
+  // Removes the physical directory a failed spawn claimed, and resolves to
+  // whether it did. It removes nothing while the directory, as the host
+  // resolves it in the turn after the last wait, holds the directory of a
+  // listed session or of another spawn's claim, or once the directory no
+  // longer resolves to itself on the host; the directory then stays for an
+  // operator to remove.
+  private async removeClaimedDir(
+    provider: ExecutionProvider,
+    id: SessionID,
+    hostKey: SessionID,
+    target: string,
+    dir: string,
+  ): Promise<boolean> {
+    if (!this.hasHostLifecycle(target)) {
+      const removed = await provider.runCommand({
+        argv: ['sh', '-c', REMOVE_DIR_SCRIPT, 'sh', dir, `${dir}\nx`],
+        cwd: '/',
+      });
+
+      return removed.exitCode === 0;
+    }
+
+    const before = this.collectHostSessionIDs(hostKey, target);
+
+    const listed = await this.resolveListedDirs(provider, hostKey, target);
+
+    if (this.collectHostSessionIDs(hostKey, target) !== before) {
+      return this.removeClaimedDir(provider, id, hostKey, target, dir);
+    }
+
+    // A directory the host could not resolve may lie inside through a
+    // symlink, so the rollback keeps its own.
+    if (listed.unresolved) {
+      return false;
+    }
+
+    const holds = this.collectOtherWorkspaceDirs(id, hostKey, target, listed.dirs).some(
+      ([, other]) => isPathWithin(other, dir),
+    );
+
+    if (holds) {
+      return false;
+    }
+
+    const slot = buildHostSlot(hostKey, target);
+
+    this.removals.set(slot, (this.removals.get(slot) ?? 0) + 1);
+
+    try {
+      const removed = await provider.runCommand({
+        argv: ['sh', '-c', REMOVE_DIR_SCRIPT, 'sh', dir, `${dir}\nx`],
+        cwd: '/',
+        host: hostKey,
+      });
+
+      return removed.exitCode === 0;
+    } finally {
+      const left = (this.removals.get(slot) ?? 1) - 1;
+
+      if (left === 0) {
+        this.removals.delete(slot);
+      } else {
+        this.removals.set(slot, left);
+      }
+    }
+  }
+
+  // The ids of the sessions listed on a host and of the plain spawns still
+  // starting there, as one string a later read compares against.
+  private collectHostSessionIDs(hostKey: SessionID, target: string): string {
+    return [
+      ...this.sessions.filter((s) => s.hostKey === hostKey && s.target === target).map((s) => s.id),
+      ...this.collectPlainDirs(hostKey, target).map(([id]) => id),
+    ].join(' ');
+  }
+
+  // The directories plain spawns still starting on a host hold, as given.
+  private collectPlainDirs(hostKey: SessionID, target: string): (readonly [SessionID, string])[] {
+    return [...this.reservations]
+      .filter(([, r]) => r.kind === 'plain' && r.hostKey === hostKey && r.target === target)
+      .map(([id, r]) => [id, r.dir] as const);
+  }
+
+  private requireSeparateWorkspace(
+    id: SessionID,
+    hostKey: SessionID,
+    target: string,
+    dir: string,
+    forms: readonly string[],
+    listed: readonly (readonly [SessionID, string])[],
+  ): void {
+    const other = this.collectOtherWorkspaceDirs(id, hostKey, target, listed).find(([, path]) =>
+      forms.some((form) => isPathOverlapping(form, path)),
+    );
+
+    if (other !== undefined) {
+      throw new DaemonError(
+        'workspace_overlap',
+        `${dir} overlaps ${other[1]}, the directory of session ${other[0]} on the same host; a workspace there lands beside it`,
+        { phase: 'resolving', dir, session: other[0] },
+      );
+    }
+  }
+
+  // The directories other sessions on a host hold: the listed ones given,
+  // and every other spawn's reservation in each form it has.
+  private collectOtherWorkspaceDirs(
+    id: SessionID,
+    hostKey: SessionID,
+    target: string,
+    listed: readonly (readonly [SessionID, string])[],
+  ): (readonly [SessionID, string])[] {
+    const dirs = [...listed];
+
+    for (const [other, r] of this.reservations) {
+      if (other !== id && r.hostKey === hostKey && r.target === target) {
+        // A relative plain directory counts only once the host resolves
+        // it, since it resolves against the session's home there.
+        dirs.push(
+          ...[r.dir, r.resolved ?? r.dir]
+            .filter((held) => posix.isAbsolute(held))
+            .map((held) => [other, held] as const),
+        );
+      }
+    }
+
+    return dirs;
+  }
+
+  // The directory of every session listed on a host, and of every plain
+  // spawn still starting there, as the host resolves it, and its own
+  // absolute form, and whether any of them failed to resolve, which a
+  // rollback treats as a directory that may lie inside its own.
+  private async resolveListedDirs(
+    provider: ExecutionProvider,
+    hostKey: SessionID,
+    target: string,
+  ): Promise<{ readonly dirs: (readonly [SessionID, string])[]; readonly unresolved: boolean }> {
+    const onHost = [
+      ...this.sessions.filter((s) => s.hostKey === hostKey && s.target === target),
+      ...this.collectPlainDirs(hostKey, target).map(([id, cwd]) => ({ id, cwd })),
+    ];
+
+    const resolved = await Promise.all(
+      onHost.map(async (s) => {
+        const dir = await this.resolveHostDir(provider, hostKey, s.cwd).catch(() => null);
+
+        const dirs: (readonly [SessionID, string])[] = [];
+
+        if (posix.isAbsolute(s.cwd)) {
+          dirs.push([s.id, s.cwd]);
+        }
+
+        if (dir !== null) {
+          dirs.push([s.id, dir]);
+        }
+
+        return { dirs, unresolved: dir === null };
+      }),
+    );
+
+    return {
+      dirs: resolved.flatMap((r) => r.dirs),
+      unresolved: resolved.some((r) => r.unresolved),
+    };
+  }
+
+  // A directory on a host with every symlink in it resolved: an absolute
+  // one through its nearest existing directory, and a relative one as a
+  // harness started in it sees it, since impd resolves both alike. A null
+  // host resolves it on the daemon's own machine.
+  private async resolveHostDir(
+    provider: ExecutionProvider,
+    hostKey: SessionID | null,
+    dir: string,
+  ): Promise<string> {
+    const absolute = posix.isAbsolute(dir);
+
+    const result = await provider.runCommand({
+      argv: ['sh', '-c', RESOLVE_DIR_SCRIPT, 'sh', absolute ? posix.normalize(dir) : '.'],
+      cwd: absolute ? '/' : dir,
+      ...(hostKey === null ? {} : { host: hostKey }),
+    });
+
+    const split = result.stdout.lastIndexOf('\0');
+
+    if (result.exitCode !== 0 || split < 1 || result.stdout[split - 1] !== '\n') {
+      throw new DaemonError(
+        'host_unavailable',
+        `${hostKey === null ? 'the daemon host' : `the host of session ${hostKey}`} cannot resolve ${dir}: ${result.stderr.trim()}`,
+        { phase: 'resolving', dir },
+      );
+    }
+
+    const existing = result.stdout.slice(0, split - 1);
+    const rest = result.stdout.slice(split + 1);
+
+    return existing === '/' ? rest || '/' : `${existing}${rest}`;
+  }
+
+  // Materializes a spawn's workspace, readying its host once the source
+  // resolves, or after the workspace for a directory that runs as it
+  // stands. A failure once the host is ready takes it back.
+  private async materializeOnSpawnHost(
+    provider: ExecutionProvider,
+    id: SessionID,
+    hostKey: SessionID,
+    target: string,
+    dir: string,
+    targetIdentity: string,
+    materialize: SpawnMaterializer,
+    setupHost: () => Promise<HarnessSetup>,
+  ): Promise<{ readonly setup: HarnessSetup; readonly materialized: MaterializedSpawn | null }> {
+    const readied: { setup: HarnessSetup | null } = { setup: null };
+
+    try {
+      const materialized = await materialize(
+        {
+          readyHost: async () => {
+            readied.setup = await setupHost();
+
+            const landing = this.hasHostLifecycle(target)
+              ? await this.claimHostDir(provider, id, hostKey, target, dir)
+              : await this.resolveHostDir(provider, null, dir);
+
+            return { host: hostKey, dir: landing };
+          },
+          removeClaim: (landing) => this.removeClaimedDir(provider, id, hostKey, target, landing),
+        },
+        targetIdentity,
+      );
+
+      readied.setup ??= await setupHost();
+
+      return { setup: readied.setup, materialized };
+    } catch (error) {
+      if (readied.setup !== null) {
+        await this.destroyFailedSpawnHost(provider, id, hostKey, readied.setup.attemptID);
+      }
+
+      throw error;
+    }
+  }
+
+  // Takes back the host a spawn readied when the spawn fails before its
+  // session lists: an attempt that provisioned the host takes back its imp
+  // and binding, and a host of the spawn's own without one is destroyed. A
+  // parent's host stays as it is. A take-back that fails throws, and a
+  // destroy that fails throws that the host may still stand.
+  private async destroyFailedSpawnHost(
+    provider: ExecutionProvider,
+    id: SessionID,
+    hostKey: SessionID,
+    attemptID: string | null,
+  ): Promise<void> {
+    if (attemptID !== null) {
+      await this.tryRemoveAuthAttempt(provider, hostKey, attemptID);
+
+      return;
+    }
+
+    if (hostKey === id && provider.capabilities.destroy) {
+      try {
+        await provider.destroyHost(hostKey);
+      } catch (error) {
+        throw new EffectRemainsError(
+          `spawn of session ${id} failed and destroying its host failed too`,
+          { cause: error },
+        );
+      }
+    }
+  }
+
   // Takes back what a spawn attempt bound when the spawn fails before its
   // session lists; a take-back that cannot be confirmed throws.
   private async tryRemoveAuthAttempt(
@@ -1105,7 +1580,7 @@ export class SessionManager {
   // behind the broker has its binding created or verified before the host
   // is readied, and a binding this call created is taken back when a later
   // step fails; the attempt that created it comes back with the plan.
-  private async setupHarness(
+  private setupHarness(
     adapter: AgentAdapter,
     provider: ExecutionProvider,
     id: SessionID,
@@ -1114,10 +1589,17 @@ export class SessionManager {
     options: SpawnOptions,
     auth: HarnessAuthSetup | null,
   ): Promise<{ readonly plan: HarnessPlan; readonly attemptID: string | null }> {
+    return this.withHostReadying(hostKey, () =>
+      this.setupHarnessOnHost(adapter, provider, id, hostKey, target, options, auth),
+    );
+  }
+
+  // Counts a host as readying while run runs, so it is not idle then.
+  private async withHostReadying<T>(hostKey: SessionID, run: () => Promise<T>): Promise<T> {
     this.readying.set(hostKey, (this.readying.get(hostKey) ?? 0) + 1);
 
     try {
-      return await this.setupHarnessOnHost(adapter, provider, id, hostKey, target, options, auth);
+      return await run();
     } finally {
       const left = (this.readying.get(hostKey) ?? 1) - 1;
 
@@ -2235,3 +2717,20 @@ function formatTargetRefusal(code: ErrorCode, target: string): string {
 
   return `target '${target}' cannot start a terminal`;
 }
+
+// Whether either of two directories on a host holds the other, or they are
+// the same.
+// The key of a shared host on one target, for state kept per host.
+function buildHostSlot(hostKey: SessionID, target: string): string {
+  return `${target}\0${hostKey}`;
+}
+
+function isPathOverlapping(a: string, b: string): boolean {
+  return isPathWithin(a, b) || isPathWithin(b, a);
+}
+
+function isPathWithin(child: string, parent: string): boolean {
+  const relative = posix.relative(parent, child);
+
+  return relative !== '..' && !relative.startsWith('../') && !posix.isAbsolute(relative);
+}

package/src/protocol/protocol.ts

@@ -43,6 +43,7 @@ const ERROR_CODES = [
   'sanitize_failed',
   'tar_failed',
   'workspace_exists',
+  'workspace_overlap',
   'transfer_failed',
   'workspace_mismatch',
   'github_unavailable',