@zgeoff/atc 2.12.0 → 2.13.0

package/src/daemon/sessions.ts

@@ -1,10 +1,16 @@
 import { writeFileSync } from 'node:fs';
-import type { AdapterEvent, AgentAdapter, AgentID, SpawnOverrides } from '../agents/agent-adapter';
+import type {
+  AdapterEvent,
+  AgentAdapter,
+  AgentID,
+  SpawnOptions,
+  SpawnOverrides,
+  SpawnPlan,
+} from '../agents/agent-adapter';
 import { truncateDetail } from '../agents/truncate-detail';
 import { DaemonError } from '../protocol/daemon-error';
 import type { ErrorCode } from '../protocol/protocol';
 import type { AgentSessionID } from '../shared/agent-session-id';
-import { collectCleanEnv } from '../shared/collect-clean-env';
 import type { TargetConfigError } from '../shared/collect-targets';
 import { socketPath, statusFile } from '../shared/config';
 import type { DaemonID } from '../shared/daemon-id';
@@ -12,13 +18,24 @@ import { resolveRepoRoot } from '../shared/resolve-repo-root';
 import type { SessionID } from '../shared/session-id';
 import { truncateToBytes } from '../shared/truncate-to-bytes';
 import type { FleetEntry, FleetEntryUpdate, FleetStore } from '../store/fleet-entry';
+import type { SessionWorkspace } from '../store/workspace-materialization';
 import type { ExecutionTarget } from './build-execution-targets';
+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 type { ExecutionCapability, ExecutionProvider, HarnessHandle } from './execution-provider';
+import type {
+  ExecutionCapability,
+  ExecutionProvider,
+  HarnessHandle,
+  HarnessRelay,
+} from './execution-provider';
 import { findExecutionRefusal } from './find-execution-refusal';
 import type { HookEvent } from './hooks';
+import type { BridgeBinding } from './is-binding-current';
 import { LocalPTYProvider } from './local-pty-provider';
 import { mintSessionID } from './mint-session-id';
+import { pickSessionState } from './pick-session-state';
 
 export type SessionState = 'running' | 'needs_you' | 'done' | 'exited';
 
@@ -55,6 +72,14 @@ export interface SessionDescriptor {
   // Where the session runs: the daemon hosting it, and the execution target
   // on that daemon's host.
   readonly locator: SessionLocator;
+
+  // What the session's working directory was materialized from, for a
+  // session spawned with a workspace source.
+  readonly workspace?: SessionWorkspace;
+
+  // What the operator asked for, the host, the harness, and the daemon's
+  // connection to it; the state derives from these and the attention.
+  readonly lifecycle: SessionLifecycle;
 }
 
 interface SessionLocator {
@@ -117,6 +142,39 @@ export interface Session {
   // while the target keeps that identity.
   target: string;
   targetIdentity: string;
+
+  // what the working directory was materialized from, when the spawn
+  // carried a workspace source
+  workspace?: SessionWorkspace;
+
+  // the environment variable names every harness the session starts goes
+  // without: the materialization's credential and askpass context
+  withheldEnv: readonly string[];
+
+  // What the operator asked of the harness, the last state seen of its
+  // host, and the daemon's connection to its output.
+  desired: SessionLifecycle['desired'];
+  vm: SessionLifecycle['vm'];
+  attachment: SessionLifecycle['attachment'];
+
+  // Whether the harness is kept inside a sleeping host, for a revive to
+  // find as it was.
+  suspended: boolean;
+
+  // The session whose host the harness runs on: its own id, or its
+  // parent's when the parent runs on the same target, so one host serves a
+  // top-level session and the sub-sessions beside it.
+  hostKey: SessionID;
+
+  // The epoch of the session's latest harness start or attach, which the
+  // daemon's bridge to that harness is bound to; 0 before the first.
+  bridgeEpoch: number;
+}
+
+// A session's ready workspace and the variables its harnesses go without.
+interface MaterializedSpawn {
+  readonly workspace: SessionWorkspace;
+  readonly withheldEnv: readonly string[];
 }
 
 // The identity of the implicit `local` target, which a fleet row without a
@@ -139,6 +197,14 @@ export class SessionManager {
 
   onChange: () => void = () => {};
 
+  // Called as a harness starts, before its first output can arrive, with
+  // the terminal size it starts at.
+  onBoot: (s: Session, cols: number, rows: number) => void = () => {};
+
+  // Takes each connection a harness's processes open through a provider's
+  // own relay, with the binding of the harness start that opened it.
+  onRelay: (binding: BridgeBinding, relay: HarnessRelay) => void = () => {};
+
   onEvent: (kind: SessionEventKind, s: Session) => void = () => {};
 
   // Where a background failure is reported, one line at a time: stderr,
@@ -162,6 +228,14 @@ export class SessionManager {
 
   private readonly targetErrors: readonly TargetConfigError[];
 
+  // Sessions whose revive waits on their host waking, so a second revive
+  // of the same session does not start a second harness.
+  private readonly adopting = new Set<SessionID>();
+
+  // The epoch the next harness start or attach takes, unique across every
+  // session this manager holds.
+  private nextBridgeEpoch = 1;
+
   constructor(
     fallback: AgentAdapter,
     store: FleetStore,
@@ -268,6 +342,24 @@ export class SessionManager {
     return s;
   }
 
+  // A sibling's revive failing leaves that sibling asleep; the session
+  // whose revive woke the host is already running, so the failure is
+  // logged rather than thrown.
+  private async tryAdoptSibling(
+    sibling: Session,
+    s: Session,
+    cols: number,
+    rows: number,
+  ): Promise<void> {
+    try {
+      await this.adoptTerminal(sibling.id, cols, rows);
+    } catch (error) {
+      this.log(
+        `atc could not revive session ${sibling.id} beside ${s.id} (${error instanceof Error ? error.message : String(error)})`,
+      );
+    }
+  }
+
   // Registers a fleet entry as a session with no terminal yet, under the
   // atc session id its row holds, so a fleet-wide restore can show every
   // incoming session at once; adopting it later attaches the terminal.
@@ -290,7 +382,9 @@ export class SessionManager {
     // reviving under another agent. Adopting a terminal for it is refused.
     let lastMsg = 'waiting to restore';
 
-    if (entry.exited !== true && entry.agentSessionID === undefined) {
+    if (exited && entry.desired === 'sleep') {
+      lastMsg = 'asleep';
+    } else if (entry.exited !== true && entry.agentSessionID === undefined) {
       lastMsg = 'nothing to resume';
     } else if (entry.exited !== true && targetRefusal !== null) {
       lastMsg = targetRefusal;
@@ -326,6 +420,14 @@ export class SessionManager {
       ...(entry.effort === undefined ? {} : { effort: entry.effort }),
       target,
       targetIdentity,
+      ...(entry.workspace === undefined ? {} : { workspace: entry.workspace }),
+      withheldEnv: entry.withheldEnv ?? [],
+      desired: entry.desired ?? 'run',
+      suspended: exited && entry.desired === 'sleep',
+      vm: this.pickRestoredVM(target, entry.desired),
+      attachment: this.hasHostLifecycle(target) ? 'detached' : 'local',
+      hostKey: entry.hostKey ?? entry.sessionID,
+      bridgeEpoch: 0,
     };
 
     this.sessions.push(session);
@@ -335,12 +437,37 @@ export class SessionManager {
     return session;
   }
 
+  // Whether a target's host has a lifecycle of its own that the daemon
+  // follows: one that can sleep or be destroyed. The daemon's own machine
+  // has none.
+  private hasHostLifecycle(target: string): boolean {
+    const capabilities = this.targets.get(target)?.provider?.capabilities;
+
+    return capabilities !== undefined && (capabilities.suspend || capabilities.destroy);
+  }
+
+  // The host state a restored session lists with: asleep when the operator
+  // left it asleep, unknown for any other remote host until the daemon
+  // reaches it, and none on the daemon's own machine.
+  private pickRestoredVM(
+    target: string,
+    desired: 'sleep' | 'stop' | undefined,
+  ): SessionLifecycle['vm'] {
+    if (!this.hasHostLifecycle(target)) {
+      return 'none';
+    }
+
+    return desired === 'sleep' ? 'asleep' : 'unknown';
+  }
+
   // Adopts a headless session back into a terminal: a fresh PTY resumes the
-  // same agent session id.
-  adoptTerminal(id: SessionID, cols: number, rows: number): Session | null {
+  // same agent session id. On a remote host the host wakes first, and a
+  // harness still running inside it is attached rather than started again;
+  // every other session left asleep on that host comes back with it.
+  async adoptTerminal(id: SessionID, cols: number, rows: number): Promise<Session | null> {
     const s = this.sessions.find((x) => x.id === id);
 
-    if (!s || s.pty !== null || s.agentSessionID === undefined) {
+    if (!s || s.pty !== null || s.agentSessionID === undefined || this.adopting.has(id)) {
       return null;
     }
 
@@ -352,49 +479,115 @@ export class SessionManager {
 
     const provider = this.requireExecution(s, 'spawn').provider;
 
-    const plan = adapter.planSpawn({
-      prompt: '',
-      resume: s.agentSessionID,
-      ...(s.model === undefined ? {} : { model: s.model }),
-      ...(s.effort === undefined ? {} : { effort: s.effort }),
-    });
+    this.adopting.add(id);
+
+    let plan: SpawnPlan;
+
+    try {
+      plan = await this.setupHarness(adapter, provider, s.id, s.hostKey, s.target, {
+        prompt: '',
+        resume: s.agentSessionID,
+        ...(s.model === undefined ? {} : { model: s.model }),
+        ...(s.effort === undefined ? {} : { effort: s.effort }),
+      });
+    } finally {
+      this.adopting.delete(id);
+    }
+
+    // A kill or a second adopt can land while the host wakes.
+    if (s.pty !== null || !this.sessions.includes(s)) {
+      return null;
+    }
+
+    const binding = this.mintBridgeBinding(s.id, s.target, s.targetIdentity, s.hostKey);
 
     const pty = provider.spawnHarness({
+      session: s.id,
+      host: s.hostKey,
       bin: plan.bin,
       args: plan.args,
       cwd: s.cwd,
-      env: collectCleanEnv({ ATC_SESSION_ID: s.id, ATC_SOCKET: socketPath }),
+      env: { ATC_SESSION_ID: s.id, ATC_SOCKET: socketPath },
+      withheldEnv: s.withheldEnv,
       cols,
       rows,
+      onRelay: (relay) => {
+        this.onRelay(binding, relay);
+      },
     });
 
+    s.bridgeEpoch = binding.epoch;
     s.pty = pty;
     s.kind = 'pty';
     s.state = 'running';
     s.lastMsg = 'revived';
+    s.desired = 'run';
+    s.suspended = false;
+
+    this.attachHarness(s, pty, this.hasHostLifecycle(s.target));
+    this.onBoot(s, cols, rows);
+    void this.tryWriteFleet(s.id);
+    this.onEvent('state', s);
+    this.emitChange();
+
+    for (const asleep of this.sessions) {
+      if (asleep.hostKey === s.hostKey && asleep.target === s.target && asleep.suspended) {
+        await this.tryAdoptSibling(asleep, s, cols, rows);
+      }
+    }
+
+    return s;
+  }
+
+  // Follows a harness's output and its end. An exit, or a host that lost the
+  // process, leaves the session exited; a host that went to sleep with the
+  // process inside leaves it suspended, for a revive to find. A session
+  // mid-handoff keeps its headless state, since the terminal dying is
+  // expected there.
+  private attachHarness(s: Session, pty: HarnessHandle, hostLifecycle: boolean): void {
+    s.vm = hostLifecycle ? 'awake' : 'none';
+    s.attachment = hostLifecycle ? 'attached' : 'local';
 
     pty.onData((d) => {
       this.onOutput(s, d);
     });
 
-    pty.onExit(() => {
+    pty.onAttachment?.((attachment) => {
+      if (s.pty !== pty || s.attachment === attachment) {
+        return;
+      }
+
+      s.attachment = attachment;
+
+      this.onEvent('state', s);
+      this.emitChange();
+    });
+
+    pty.onExit((exit) => {
+      if (s.pty !== pty) {
+        return;
+      }
+
       s.pty = null;
 
+      if (hostLifecycle) {
+        s.attachment = 'detached';
+      }
+
       if (s.kind === 'pty' && s.state !== 'exited') {
         s.state = 'exited';
         s.unread = this.focusedId !== s.id;
-        s.lastMsg = 'process exited';
+        s.lastMsg = pickExitMessage(exit);
+      }
+
+      if (exit.reason === 'suspended') {
+        s.vm = 'asleep';
+        s.suspended = true;
       }
 
       this.onEvent('state', s);
       this.emitChange();
     });
-
-    void this.tryWriteFleet(s.id);
-    this.onEvent('state', s);
-    this.emitChange();
-
-    return s;
   }
 
   /**
@@ -491,8 +684,10 @@ 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.
-  spawn(
+  // 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.
+  async spawn(
     cwd: string,
     name: string,
     prompt: string,
@@ -505,7 +700,8 @@ export class SessionManager {
     overrides: SpawnOverrides = {},
     id: SessionID = mintSessionID(),
     target = 'local',
-  ): Session {
+    materialized: MaterializedSpawn | null = null,
+  ): Promise<Session> {
     const adapter = this.findAdapter(agent);
 
     if (adapter === null) {
@@ -516,17 +712,32 @@ export class SessionManager {
     const provider = execution.provider;
 
     // The repository root resolves before the process starts: resolving it
-    // can throw, and a spawn that throws must leave nothing running.
-    const repoRoot = resolveRepoRoot(cwd);
-    const plan = adapter.planSpawn({ prompt, resume, ...overrides });
+    // can throw, and a spawn that throws must leave nothing running. A
+    // remote directory is not on the daemon's machine, so it is its own root.
+    const repoRoot = provider.remote ? cwd : resolveRepoRoot(cwd);
+    const hostKey = this.pickHostKey(id, parent, target, execution.identity);
+
+    const plan = await this.setupHarness(adapter, provider, id, hostKey, target, {
+      prompt,
+      resume,
+      ...overrides,
+    });
+
+    const binding = this.mintBridgeBinding(id, target, execution.identity, hostKey);
 
     const pty = provider.spawnHarness({
+      session: id,
+      host: hostKey,
       bin: plan.bin,
       args: plan.args,
       cwd,
-      env: collectCleanEnv({ ATC_SESSION_ID: id, ATC_SOCKET: socketPath }),
+      env: { ATC_SESSION_ID: id, ATC_SOCKET: socketPath },
+      withheldEnv: materialized?.withheldEnv ?? [],
       cols,
       rows,
+      onRelay: (relay) => {
+        this.onRelay(binding, relay);
+      },
     });
 
     let initialMsg = prompt;
@@ -557,33 +768,123 @@ export class SessionManager {
       ...(overrides.effort === undefined ? {} : { effort: overrides.effort }),
       target,
       targetIdentity: execution.identity,
+      ...(materialized === null ? {} : { workspace: materialized.workspace }),
+      withheldEnv: materialized?.withheldEnv ?? [],
+      desired: 'run',
+      vm: 'none',
+      attachment: 'local',
+      suspended: false,
+      hostKey,
+      bridgeEpoch: binding.epoch,
     };
 
-    pty.onData((d) => {
-      this.onOutput(session, d);
+    this.attachHarness(session, pty, this.hasHostLifecycle(target));
+    this.sessions.push(session);
+    void this.tryWriteFleet(session.id);
+    this.writeStatus();
+    this.onEvent('added', session);
+    this.onBoot(session, cols, rows);
+
+    return session;
+  }
+
+  // The binding a harness start or attach opens its bridge under, at a
+  // fresh epoch.
+  private mintBridgeBinding(
+    sessionID: SessionID,
+    target: string,
+    targetIdentity: string,
+    hostKey: SessionID,
+  ): BridgeBinding {
+    const epoch = this.nextBridgeEpoch;
+
+    this.nextBridgeEpoch += 1;
+
+    return { sessionID, target, targetIdentity, hostKey, epoch };
+  }
+
+  // Readies the host a harness is about to start on and plans the harness.
+  // On a remote host the agent plans a guest spawn, whose files unpack into
+  // the session's own guest folder, and the agent's sign-in check runs
+  // there first. Every refusal comes before the harness starts.
+  private async setupHarness(
+    adapter: AgentAdapter,
+    provider: ExecutionProvider,
+    id: SessionID,
+    hostKey: SessionID,
+    target: string,
+    options: SpawnOptions,
+  ): Promise<SpawnPlan> {
+    if (!provider.remote) {
+      await provider.prepareHost({ host: hostKey, daemonID: this.store.daemonID });
+
+      return adapter.planSpawn(options);
+    }
+
+    const guest = provider.guest ?? { dir: '/tmp/atc', atc: null };
+    const dir = `${guest.dir}/sessions/${id}`;
+
+    const plan =
+      adapter.planGuestSpawn === undefined
+        ? { ...adapter.planSpawn(options), files: {} }
+        : adapter.planGuestSpawn(options, { atc: guest.atc, dir });
+
+    if (plan === null) {
+      throw buildGuestRefusal(provider.kind, adapter.id, target, guest.atc === null);
+    }
+
+    await provider.prepareHost({
+      host: hostKey,
+      daemonID: this.store.daemonID,
+      installATC: adapter.planGuestSpawn !== undefined,
     });
 
-    pty.onExit(() => {
-      session.pty = null;
+    const check = adapter.planAuthCheck?.();
 
-      // A session mid-handoff keeps its headless state; the terminal dying
-      // is expected there, not an exit.
-      if (session.kind === 'pty' && session.state !== 'exited') {
-        session.state = 'exited';
-        session.unread = this.focusedId !== session.id;
-        session.lastMsg = 'process exited';
+    if (check !== undefined) {
+      const result = await provider.runCommand({ argv: check, cwd: '/', host: hostKey });
+
+      if (result.exitCode !== 0) {
+        throw new DaemonError(
+          'auth_not_configured',
+          `agent '${adapter.id}' is not signed in on target '${target}'; sign it in inside the host's image`,
+          { agent: adapter.id, target },
+        );
       }
+    }
 
-      this.onEvent('state', session);
-      this.emitChange();
-    });
+    const files = Object.entries(plan.files).map(([path, content]) => ({ path, content }));
 
-    this.sessions.push(session);
-    void this.tryWriteFleet(session.id);
-    this.writeStatus();
-    this.onEvent('added', session);
+    if (files.length > 0) {
+      await provider.transferArchive(buildTarArchive(files), dir, hostKey);
+    }
 
-    return session;
+    return plan;
+  }
+
+  // A sub-session runs on its parent's host when its resolved target, name
+  // and identity both, is the one its parent is bound to and that target's
+  // hosts have a lifecycle, so one host serves a top-level session and
+  // every sub-session beside it there; any other session has a host of its
+  // own.
+  private pickHostKey(
+    id: SessionID,
+    parent: SessionID | null,
+    target: string,
+    identity: string,
+  ): SessionID {
+    const owner = parent === null ? undefined : this.sessions.find((s) => s.id === parent);
+
+    if (
+      owner === undefined ||
+      owner.target !== target ||
+      owner.targetIdentity !== identity ||
+      !this.hasHostLifecycle(target)
+    ) {
+      return id;
+    }
+
+    return owner.hostKey;
   }
 
   // Takes back a spawn that failed after its process started: the process
@@ -612,7 +913,7 @@ export class SessionManager {
       id: s.id,
       name: s.name,
       cwd: s.cwd,
-      state: s.state,
+      state: pickSessionState(buildLifecycle(s), s.state),
       unread: s.unread,
       lastMsg: s.lastMsg,
       ...(s.lastDetail === undefined ? {} : { lastDetail: s.lastDetail }),
@@ -628,6 +929,8 @@ export class SessionManager {
       canEject: (this.findAdapter(s.agent)?.headlessRunner ?? null) !== null,
       ...(s.parent === null ? {} : { parent: s.parent }),
       locator: { daemonID: this.store.daemonID, targetID: s.target },
+      ...(s.workspace === undefined ? {} : { workspace: s.workspace }),
+      lifecycle: buildLifecycle(s),
     }));
   }
 
@@ -835,7 +1138,12 @@ export class SessionManager {
   // archived, so the write it depends on must land before that response
   // goes out. A kill acts on the whole set: killing a session kills its
   // live sub-sessions with it, and forgetting a dead one forgets its dead
-  // sub-sessions and promotes any live ones to top level.
+  // sub-sessions and promotes any live ones to top level. A live session
+  // that owns a host that can sleep puts the host to sleep instead, with
+  // every harness on it kept inside, and fails whole when the host stays
+  // awake. A dead session on a target that can destroy its host is not
+  // forgotten by a kill: forgetting it destroys the host, which takes a
+  // confirmed forget.
   async kill(id: SessionID): Promise<void> {
     const s = this.sessions.find((x) => x.id === id);
 
@@ -844,28 +1152,181 @@ export class SessionManager {
     }
 
     if (s.pty) {
+      await this.stopHarness(s);
+
       for (const child of this.collectChildren(id)) {
-        this.killTerminal(child);
+        await this.tryStopHarness(child);
       }
-
-      this.killTerminal(s);
     } else {
-      for (const child of this.collectChildren(id)) {
-        if (child.pty === null && !(child.kind === 'headless' && child.state !== 'exited')) {
-          this.remove(child);
-        } else {
-          child.parent = null;
+      if (this.findProvider(s)?.capabilities.destroy === true) {
+        throw new DaemonError(
+          'confirmation_required',
+          `forgetting session ${id} destroys its host on target '${s.target}'; confirm it with session.forget`,
+          { session: id },
+        );
+      }
+
+      this.updateForgottenChildren(id);
+      this.remove(s);
+    }
+
+    await this.writeFleet();
+
+    this.emitChange();
+  }
+
+  /**
+   * Forgets a session for good, whether it runs or not, and returns whether
+   * its host was destroyed. A session that owns a host its target can
+   * destroy destroys the host, and every session on that host goes with it;
+   * a session on its parent's host ends its own harness alone, and one
+   * kept asleep in that host is refused until the host wakes. Its dead
+   * sub-sessions on other hosts go with it, unless their own target can
+   * destroy their host, and its live ones become top-level. A failed destroy
+   * throws before anything is forgotten.
+   */
+  async forget(id: SessionID): Promise<boolean> {
+    const s = this.sessions.find((x) => x.id === id);
 
-          this.onEvent('state', child);
+    if (s === undefined) {
+      return false;
+    }
+
+    const provider = this.findProvider(s);
+    const destroys = provider !== null && provider.capabilities.destroy && s.hostKey === s.id;
+
+    // A harness kept inside a sleeping host it does not own still has a
+    // process there, which the daemon can neither reach nor end while the
+    // host sleeps. Its record keeps that process owned until the host wakes
+    // or its owner's forget destroys the host.
+    if (!destroys && s.pty === null && s.vm === 'asleep') {
+      throw new DaemonError(
+        'unsupported_operation',
+        `session ${id} sleeps inside the host of session ${s.hostKey}; revive it or forget session ${s.hostKey} first`,
+        { provider: provider?.kind ?? null, problem: 'host_asleep', host: s.hostKey },
+      );
+    }
+
+    if (destroys) {
+      await provider.destroyHost(s.hostKey);
+
+      for (const onHost of this.sessions) {
+        if (onHost.hostKey === s.hostKey && onHost.target === s.target && onHost.id !== s.id) {
+          onHost.pty?.detach();
+          onHost.pty = null;
+
+          this.remove(onHost);
         }
       }
 
-      this.remove(s);
+      s.pty?.detach();
+      s.pty = null;
+    } else {
+      this.killTerminal(s);
     }
 
+    this.updateForgottenChildren(id);
+    this.remove(s);
+
     await this.writeFleet();
 
     this.emitChange();
+
+    return destroys;
+  }
+
+  // A forgotten parent's dead sub-sessions go with it, except one whose own
+  // target can destroy its host: forgetting that one destroys the host, which
+  // takes its own confirmed forget. Every sub-session that stays becomes
+  // top-level.
+  private updateForgottenChildren(id: SessionID): void {
+    for (const child of this.collectChildren(id)) {
+      const live = child.pty !== null || (child.kind === 'headless' && child.state !== 'exited');
+
+      if (live || this.findProvider(child)?.capabilities.destroy === true) {
+        child.parent = null;
+
+        this.onEvent('state', child);
+      } else {
+        this.remove(child);
+      }
+    }
+  }
+
+  /**
+   * The capability a kill of a live session needs on its target: `suspend`
+   * for a session that owns a host that can sleep, `kill` for any other.
+   */
+  pickKillCapability(s: Session): ExecutionCapability {
+    return this.canSuspendHost(s) ? 'suspend' : 'kill';
+  }
+
+  private canSuspendHost(s: Session): boolean {
+    return s.hostKey === s.id && this.findProvider(s)?.capabilities.suspend === true;
+  }
+
+  // Puts the session's host to sleep when it owns one that can sleep, and
+  // ends its harness otherwise. A refused sleep throws before anything
+  // changes.
+  private async stopHarness(s: Session): Promise<void> {
+    const provider = this.findProvider(s);
+
+    if (provider === null || !this.canSuspendHost(s)) {
+      this.killTerminal(s);
+
+      return;
+    }
+
+    await provider.suspendHost(s.hostKey);
+
+    for (const onHost of this.sessions) {
+      if (onHost.hostKey === s.hostKey && onHost.target === s.target) {
+        this.updateSuspended(onHost);
+      }
+    }
+  }
+
+  // A sub-session whose host stays awake is ended instead, so a kill
+  // never leaves part of its set running.
+  private async tryStopHarness(s: Session): Promise<void> {
+    if (s.pty === null) {
+      this.killTerminal(s);
+
+      return;
+    }
+
+    try {
+      await this.stopHarness(s);
+    } catch (error) {
+      this.log(
+        `atc could not put the host of session ${s.id} to sleep (${error instanceof Error ? error.message : String(error)}); ending its harness instead`,
+      );
+
+      this.killTerminal(s);
+    }
+  }
+
+  // A harness inside a host that went to sleep: the daemon lets go of it,
+  // and the process stays inside the host for a revive to find.
+  private updateSuspended(s: Session): void {
+    s.vm = 'asleep';
+
+    if (s.pty === null) {
+      this.onEvent('state', s);
+
+      return;
+    }
+
+    s.pty.detach();
+
+    s.pty = null;
+    s.state = 'exited';
+    s.lastMsg = 'asleep';
+    s.desired = 'sleep';
+    s.attachment = 'detached';
+    s.suspended = true;
+
+    this.onEvent('state', s);
   }
 
   // Ends a live session, terminal or headless, leaving a dead entry; a
@@ -881,6 +1342,7 @@ export class SessionManager {
 
     s.state = 'exited';
     s.lastMsg = 'killed';
+    s.desired = 'stop';
 
     this.onEvent('state', s);
   }
@@ -895,9 +1357,12 @@ export class SessionManager {
     this.onEvent('removed', s);
   }
 
-  killAll() {
+  // Lets go of every harness as the daemon stops: one on the daemon's own
+  // machine ends with it, and one on a remote host runs on for the next
+  // daemon to attach.
+  detachAll() {
     for (const s of this.sessions) {
-      s.pty?.kill();
+      s.pty?.detach();
     }
   }
 
@@ -946,6 +1411,8 @@ export class SessionManager {
         ...(s.effort === undefined ? {} : { effort: s.effort }),
         target: s.target,
         targetIdentity: s.targetIdentity,
+        ...(s.desired === 'run' ? {} : { desired: s.desired }),
+        ...(s.hostKey === s.id ? {} : { hostKey: s.hostKey }),
       });
     }
 
@@ -1089,6 +1556,52 @@ export function sortGroupedSessionViews<
   return [...buckets.values()].flat();
 }
 
+function buildLifecycle(s: Session): SessionLifecycle {
+  return buildSessionLifecycle({
+    desired: s.desired,
+    vm: s.vm,
+    attachment: s.attachment,
+    suspended: s.suspended,
+    hasHarness: s.pty !== null,
+    kind: s.kind,
+    state: s.state,
+  });
+}
+
+// An agent that plans no remote spawn: for want of an atc inside the host
+// when the host has none, or because the agent never runs remotely.
+function buildGuestRefusal(
+  provider: string,
+  agent: string,
+  target: string,
+  hasNoATC: boolean,
+): DaemonError {
+  return hasNoATC
+    ? new DaemonError(
+        'unsupported_operation',
+        `agent '${agent}' cannot run on target '${target}': its host has no atc to report through; run a compiled atc daemon on Linux, or set the target's guestATC to an atc installed in its image`,
+        { provider, agent, problem: 'no_guest_atc' },
+      )
+    : new DaemonError(
+        'unsupported_operation',
+        `agent '${agent}' cannot run on a remote target such as '${target}'`,
+        { provider, agent, problem: 'remote_unsupported' },
+      );
+}
+
+// Why a harness stopped, as a session's last message.
+function pickExitMessage(exit: Readonly<{ reason?: string; detail?: string }>): string {
+  if (exit.reason === 'suspended') {
+    return 'asleep';
+  }
+
+  if (exit.reason === 'ended') {
+    return exit.detail ?? 'host lost the process';
+  }
+
+  return 'process exited';
+}
+
 // A target refusal as a session's last message, short enough for a list row.
 function formatTargetRefusal(code: ErrorCode, target: string): string {
   if (code === 'target_config_invalid') {