@zgeoff/atc 2.24.0 → 2.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgeoff/atc",
-  "version": "2.24.0",
+  "version": "2.25.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/agents/agent-adapter.ts

@@ -3,6 +3,8 @@ import type { DaemonError } from '../protocol/daemon-error';
 import type { HookEvent } from '../protocol/hook-event';
 import type { AgentID } from '../shared/agent-id';
 import type { AgentSessionID } from '../shared/agent-session-id';
+import type { AuthProfile } from '../shared/collect-auth-profiles';
+import type { GatewayAuth, GatewayConfig } from '../shared/collect-gateways';
 import type { SessionID } from '../shared/session-id';
 
 export interface SpawnOptions {
@@ -35,19 +37,36 @@ export interface SpawnPlan {
 /**
  * Where a session on a remote host finds atc: the atc binary inside the
  * host, null when the host has none, and the folder the session's own
- * files unpack into.
+ * files unpack into. `auth` is given when the harness takes its credential
+ * from impd's broker: the revision of the host's runtime auth binding it
+ * launches under, which keys any settings the agent writes for it, and the
+ * placeholder variables the harness holds in place of a credential.
  */
 export interface GuestPaths {
   readonly atc: string | null;
   readonly dir: string;
+  readonly auth?: { readonly revision: number; readonly env: Readonly<Record<string, string>> };
+}
+
+/**
+ * The credential an agent takes from impd's broker instead of holding it:
+ * its gateway's endpoint and auth selection, and the auth profiles that
+ * selection resolves against.
+ */
+export interface AuthSelection {
+  readonly gateway: Pick<GatewayConfig, 'id' | 'baseURL'> & { readonly auth: GatewayAuth };
+  readonly profiles: ReadonlyMap<string, AuthProfile>;
 }
 
 /**
  * A spawn on a remote host, with the files the harness reads there, keyed
- * by their path inside the session's guest folder.
+ * by their path inside the session's guest folder, and the variables the
+ * harness process starts with, which no variable the harness inherits
+ * overrides.
  */
 export interface GuestSpawnPlan extends SpawnPlan {
   readonly files: Readonly<Record<string, string>>;
+  readonly env?: Readonly<Record<string, string>>;
 }
 
 export interface TranscriptToolUse {
@@ -204,8 +223,14 @@ export interface AgentAdapter {
   // Plans a spawn on a remote host; null when this agent cannot run there,
   // such as one whose instrumentation needs atc on a host without it.
   // Absent: the agent runs there as a local spawn plans it, with no files.
+  // A plan for a guest whose `auth` is given that cannot launch behind the
+  // broker is null.
   readonly planGuestSpawn?: (opts: SpawnOptions, guest: GuestPaths) => GuestSpawnPlan | null;
 
+  // The credential this agent takes from impd's broker, or null when it
+  // takes none. Absent: it takes none.
+  readonly findAuthSelection?: () => AuthSelection | null;
+
   // The refusal every start of this agent's harness gets, on any target,
   // or null when it may start. Absent: no start is refused.
   readonly findSpawnRefusal?: () => DaemonError | null;

package/src/agents/gateway-adapter.ts

@@ -9,6 +9,7 @@ import { toShellArg } from '../shared/to-shell-arg';
 import type {
   AgentAdapter,
   AgentProfile,
+  AuthSelection,
   HeadlessRunner,
   NameUpdate,
   ResumeCheck,
@@ -59,6 +60,8 @@ export class GatewayAdapter implements AgentAdapter {
 
   private readonly gateway: GatewayConfig;
 
+  private readonly config: Config;
+
   private readonly claude: ClaudeAdapter;
 
   // Written on first spawn so constructing the adapter touches no state.
@@ -77,6 +80,7 @@ export class GatewayAdapter implements AgentAdapter {
   ) {
     this.bridgeTarget = bridgeTarget;
     this.gateway = gateway;
+    this.config = config;
     this.id = gateway.id;
 
     const models = pickModels(gateway.env);
@@ -102,8 +106,9 @@ export class GatewayAdapter implements AgentAdapter {
           });
   }
 
-  // A gateway whose credential comes through impd's broker never starts
-  // until the broker path exists: started without it, the CLI would send
+  // A gateway whose credential comes through impd's broker starts only in a
+  // guest that reaches the broker, with guest settings the adapter plans
+  // for it, and it plans none: started without them, the CLI would send
   // whatever credential it holds to the gateway's host.
   findSpawnRefusal(): DaemonError | null {
     if (this.gateway.auth === undefined) {
@@ -112,11 +117,24 @@ export class GatewayAdapter implements AgentAdapter {
 
     return new DaemonError(
       'auth_target_unsupported',
-      `gateway '${this.id}' takes its credential from impd's broker, and brokered credentials are not wired yet`,
+      `gateway '${this.id}' takes its credential from impd's broker, and atc plans no guest settings for it on any target`,
       { agent: this.id },
     );
   }
 
+  findAuthSelection(): AuthSelection | null {
+    const auth = this.gateway.auth;
+
+    if (auth === undefined) {
+      return null;
+    }
+
+    return {
+      gateway: { id: this.gateway.id, baseURL: this.gateway.baseURL, auth },
+      profiles: this.config.authProfiles,
+    };
+  }
+
   planSpawn(opts: SpawnOptions): SpawnPlan {
     return {
       bin: this.gateway.bin,

package/src/client/collect-target-picks.ts

@@ -13,6 +13,10 @@ export interface TargetPick {
   // Whether a session there runs on the daemon's own machine, where a
   // local directory runs in place.
   readonly inPlace: boolean;
+
+  // Whether the target reaches impd's credential broker; false from a
+  // daemon that does not say.
+  readonly brokerAuth: boolean;
 }
 
 /**
@@ -47,6 +51,7 @@ export function collectTargetPicks(answer: Readonly<Record<string, unknown>>): T
         takesWorkspace:
           available && capabilities['transfer'] === true && capabilities['run'] === true,
         inPlace: entry['provider'] === 'local-pty',
+        brokerAuth: entry['brokerAuth'] === true,
       },
     ];
   });

package/src/client/spawn-picker.ts

@@ -1616,7 +1616,10 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
       return;
     }
 
-    const picks = collectTargetPicks(listed);
+    // An agent that takes its credential from impd's broker runs only on a
+    // target that reaches the broker.
+    const brokered = isBrokerAgent(listed['agents'], this.agent);
+    const picks = collectTargetPicks(listed).filter((t) => !brokered || t.brokerAuth);
 
     // An adopt resumes a session from its history on this host, which a
     // fresh checkout elsewhere does not hold, so it is offered only the
@@ -1870,6 +1873,17 @@ function buildProbedRepo(
   };
 }
 
+// Whether the daemon lists an agent as taking its credential from impd's
+// broker; a daemon that does not say lists none.
+function isBrokerAgent(raw: unknown, agent: AgentID): boolean {
+  return (
+    Array.isArray(raw) &&
+    raw.some(
+      (entry: unknown) => isRecord(entry) && entry['id'] === agent && entry['brokerAuth'] === true,
+    )
+  );
+}
+
 function parseAnnouncedSources(raw: unknown): AnnouncedSource[] {
   if (!Array.isArray(raw)) {
     return [];

package/src/daemon/broker-auth-host.ts

@@ -0,0 +1,25 @@
+import type { ImpPort, ImpView } from './imp-port';
+
+/**
+ * What a provider whose hosts can reach impd's credential broker offers
+ * runtime auth: the literal start of every imp name it builds, the imp a
+ * host key runs on, impd's identity, secret and grant calls, and creating
+ * and destroying a host's imp the way the provider itself does. A
+ * destroy that finds no imp counts as done.
+ */
+export interface BrokerAuthHost {
+  readonly impPrefix: string;
+  readonly port: Pick<
+    ImpPort,
+    | 'readFeatures'
+    | 'readIdentity'
+    | 'readSecrets'
+    | 'readGrants'
+    | 'createGrant'
+    | 'removeGrant'
+    | 'readImp'
+  >;
+  readonly getImpName: (hostKey: string) => string;
+  readonly createImp: (hostKey: string) => Promise<ImpView>;
+  readonly destroyImp: (hostKey: string) => Promise<void>;
+}

package/src/daemon/broker-authority-error.ts

@@ -2,7 +2,8 @@
  * Why impd's credential broker may not be used for a session, or why atc
  * may not clean up after one:
  *
- * - `auth_impd_too_old`: impd lacks grantable tokens or secret rebinds.
+ * - `auth_impd_too_old`: impd lacks grantable tokens, secret rebinds or
+ *   exec requirements.
  * - `auth_token_scope`: the token's scope is below `manage`.
  * - `auth_token_too_broad`: the token can reach imps outside atc's
  *   namespace, through no imp patterns or a pattern whose literal text

package/src/daemon/build-agent-list.ts

@@ -2,7 +2,8 @@ import type { AgentAdapter, SpawnOptionSpec } from '../agents/agent-adapter';
 
 interface AgentCapabilities {
   // Only an installed agent whose starts are not all refused can start a
-  // session.
+  // session, and one that takes its credential from impd's broker only
+  // where some target reaches the broker.
   readonly spawn: boolean;
   readonly readTranscript: boolean;
 
@@ -20,6 +21,10 @@ export interface AgentEntry {
 
   // Whether the agent's binary resolves, on PATH or at its configured path.
   readonly installed: boolean;
+
+  // Whether the agent takes its credential from impd's broker, so it runs
+  // only on a target whose entry has `brokerAuth`.
+  readonly brokerAuth: boolean;
   readonly capabilities: AgentCapabilities;
   readonly models: Readonly<Record<string, string>> | null;
   readonly spawnOptions: SpawnOptionEntries;
@@ -43,22 +48,30 @@ interface SpawnOptionEntries {
  * so no environment value, credential, helper command, or base URL reaches
  * it. Every session runs in a PTY, so each agent can be attached, read as a
  * screen, and typed into. A stand-in adapter without a profile is listed
- * under its id as both label and kind.
+ * under its id as both label and kind. hasBrokerTarget holds whether any
+ * target reaches impd's credential broker.
  */
 export function buildAgentList(
   adapters: readonly AgentAdapter[],
   isInstalled: (bin: string) => boolean,
+  hasBrokerTarget: boolean,
 ): AgentEntry[] {
   return adapters.map((adapter) => {
     const profile = adapter.profile;
     const installed = profile === undefined ? false : isInstalled(profile.bin);
-    const spawnable = installed && (adapter.findSpawnRefusal?.() ?? null) === null;
+    const brokerAuth = (adapter.findAuthSelection?.() ?? null) !== null;
+
+    const spawnable =
+      installed &&
+      (adapter.findSpawnRefusal?.() ?? null) === null &&
+      (!brokerAuth || hasBrokerTarget);
 
     return {
       id: adapter.id,
       label: profile?.label ?? adapter.id,
       kind: profile?.kind ?? adapter.id,
       installed,
+      brokerAuth,
       capabilities: {
         spawn: spawnable,
         readTranscript: adapter.parseTranscriptLine !== undefined,

package/src/daemon/build-scoped-context.ts

@@ -139,6 +139,8 @@ export function buildScopedContext(
     // out or taken, so its host is never touched.
     forgetSession: (id, confirmToken) =>
       canSee(id) ? ctx.forgetSession(id, confirmToken) : Promise.resolve('missing' as const),
+    revokeSessionAuth: (id) => (canSee(id) ? ctx.revokeSessionAuth(id) : Promise.resolve(false)),
+    updateSessionAuth: (id) => (canSee(id) ? ctx.updateSessionAuth(id) : Promise.resolve(null)),
     updateSession: (id, name, pinned) => canSee(id) && ctx.updateSession(id, name, pinned),
     ackSession: (id) => canSee(id) && ctx.ackSession(id),
     buildResumeCommand: (id) => (canSee(id) ? ctx.buildResumeCommand(id) : null),

package/src/daemon/build-target-list.ts

@@ -14,6 +14,10 @@ export interface TargetEntry {
   readonly available: boolean;
   readonly default: boolean;
   readonly capabilities: ExecutionCapabilities;
+
+  // Whether the target's provider reaches impd's credential broker, so an
+  // agent that takes its credential from the broker can run there.
+  readonly brokerAuth: boolean;
 }
 
 // What a target without a provider can do: nothing.
@@ -46,5 +50,6 @@ export function buildTargetList(
     available: target.provider !== null,
     default: target.id === defaultTarget,
     capabilities: target.provider?.capabilities ?? NO_CAPABILITIES,
+    brokerAuth: target.provider?.brokerAuth !== undefined,
   }));
 }

package/src/daemon/daemon-connection.ts

@@ -34,8 +34,14 @@ interface RequestScope {
   readonly keyNamespace: string;
 }
 
-// The requests that act on the whole daemon, which only its owner may make.
-const OWNER_METHODS: ReadonlySet<string> = new Set(['daemon.quit', 'fleet.restore']);
+// The requests that act on the whole daemon, or on the credentials a
+// session's host may use, which only its owner may make.
+const OWNER_METHODS: ReadonlySet<string> = new Set([
+  'daemon.quit',
+  'fleet.restore',
+  'session.auth.revoke',
+  'session.auth.rebind',
+]);
 
 // What a limited connection is sent for one event, and the sessions that
 // event moved out of its view.
@@ -648,6 +654,48 @@ export class DaemonConnection {
 
         return;
       }
+      case 'session.auth.revoke': {
+        const parsed = parseRequestParams('session.auth.revoke', req.p);
+
+        if (!parsed.ok) {
+          this.sendErr(req.id, 'bad_args', parsed.message);
+
+          return;
+        }
+
+        const id = parsed.data.session;
+
+        const revoked = await ctx.revokeSessionAuth(id);
+
+        if (revoked) {
+          this.sendOk(req.id, { revoked: true });
+        } else {
+          this.sendErr(req.id, 'no_such_session', `no session '${id}'`);
+        }
+
+        return;
+      }
+      case 'session.auth.rebind': {
+        const parsed = parseRequestParams('session.auth.rebind', req.p);
+
+        if (!parsed.ok) {
+          this.sendErr(req.id, 'bad_args', parsed.message);
+
+          return;
+        }
+
+        const id = parsed.data.session;
+
+        const revision = await ctx.updateSessionAuth(id);
+
+        if (revision === null) {
+          this.sendErr(req.id, 'no_such_session', `no session '${id}'`);
+        } else {
+          this.sendOk(req.id, { revision });
+        }
+
+        return;
+      }
       case 'session.resumeCommand': {
         const parsed = parseRequestParams('session.resumeCommand', req.p);
 
@@ -901,6 +949,8 @@ export class DaemonConnection {
         throw refusal;
       }
 
+      ctx.requireAgentTarget(agent, target);
+
       const overrides = parseSpawnOverrides(entry, { model: data.model, effort: data.effort });
 
       if (!overrides.ok) {

package/src/daemon/daemon-context.ts

@@ -180,6 +180,10 @@ export interface DaemonContext {
   // one whose provider cannot both transfer an archive and run a command.
   readonly requireWorkspaceTarget: (target: string) => void;
 
+  // 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;
+
   // The source the daemon offers the spawn picker under an id, or null when
   // it offers none under it.
   readonly findSource: (id: string) => SourceProvider | null;
@@ -211,6 +215,14 @@ export interface DaemonContext {
     id: SessionID,
     confirmToken: string | undefined,
   ) => Promise<ForgetResult | 'missing'>;
+
+  // Withdraws the grants of the runtime auth binding on a session's host,
+  // and answers false for no such session.
+  readonly revokeSessionAuth: (id: SessionID) => Promise<boolean>;
+
+  // Binds a session's host to its agent's current auth selection, and
+  // answers the new revision, or null for no such session.
+  readonly updateSessionAuth: (id: SessionID) => Promise<number | null>;
   readonly updateSession: (id: SessionID, name?: string, pinned?: boolean) => boolean | 'child_pin';
   readonly quitDaemon: () => void;
   readonly ackSession: (id: SessionID) => boolean;

package/src/daemon/daemon.ts

@@ -77,6 +77,7 @@ import { PermissionRegistry } from './permission-registry';
 import { requireGitTransports } from './require-git-transports';
 import { restoreFleet } from './restore-fleet';
 import { runEjectHandoff } from './run-eject-handoff';
+import { RuntimeAuthBinder } from './runtime-auth-binder';
 import { ScreenModel } from './screen-model';
 import { SessionRuntime } from './session-runtime';
 import { SessionManager } from './sessions';
@@ -278,6 +279,7 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
   // that stopped mid-effect is settled, so no retry can race either.
   await store.reconcileMaterializations(Date.now());
   await store.reconcileIdempotencyKeys(Date.now());
+  await store.reconcileAuthBindings(Date.now());
 
   await tryRemoveExpiredIdempotencyKeys(store);
 
@@ -317,6 +319,14 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
     mgr.log = opts.log;
   }
 
+  const authBinder = new RuntimeAuthBinder(store);
+
+  mgr.authBinder = authBinder;
+
+  // Settled in the background, since it reaches impd: each binding a
+  // stopped daemon left mid-change stays blocked until it is settled.
+  void tryReconcileAuthBindings(authBinder, store, targetsByID, mgr.log);
+
   const clients = new Set<DaemonConnection>();
 
   const runHooks = makeHookRunner(opts.hooks ?? {});
@@ -1272,7 +1282,11 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
         arch: process.arch,
         build: opts.build,
       },
-      agents: buildAgentList(mgr.collectAdapters(), (bin) => Bun.which(bin) !== null),
+      agents: buildAgentList(
+        mgr.collectAdapters(),
+        (bin) => Bun.which(bin) !== null,
+        targets.some((target) => target.provider?.brokerAuth !== undefined),
+      ),
       targets: buildTargetList(targets, defaultTarget),
       spawnDefaults: { agent: 'claude', target: defaultTarget },
       configRevision,
@@ -1324,6 +1338,9 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
       mgr.requireExecution({ target, targetIdentity: null }, 'transfer');
       mgr.requireExecution({ target, targetIdentity: null }, 'run');
     },
+    requireAgentTarget: (agent, target) => {
+      mgr.requireAgentTarget(agent, target);
+    },
     findSource: (id) => sources.find((source) => source.id === id) ?? null,
     collectAlternateGitURLs: (url) => [
       ...new Set(sources.flatMap((source) => source.findAlternateURLs?.(url) ?? [])),
@@ -1446,6 +1463,8 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
 
       return { forgotten: true, destroyed };
     },
+    revokeSessionAuth: (id) => mgr.revokeAuth(id),
+    updateSessionAuth: (id) => mgr.updateAuth(id),
     ejectSession: (id, prompt) => {
       const s = mgr.sessions.find((x) => x.id === id);
 
@@ -1494,6 +1513,14 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
         return 'no_transcript';
       }
 
+      const listed = mgr.sessions.find((s) => s.id === id);
+
+      // Refused before the headless run stops, so a refusal leaves it as
+      // it was.
+      if (listed !== undefined) {
+        mgr.requireAgentTarget(listed.agent, listed.target);
+      }
+
       const runtime = runtimes.get(id);
 
       runtime?.stopHeadlessRun();
@@ -2197,6 +2224,36 @@ async function tryRemoveExpiredIdempotencyKeys(store: StateStore): Promise<boole
   return true;
 }
 
+// Settles the runtime auth bindings a stopped daemon left mid-change, each
+// through its target's broker; a host with a fleet entry is listed, and a
+// failure is logged and leaves its binding blocked.
+async function tryReconcileAuthBindings(
+  binder: RuntimeAuthBinder,
+  store: StateStore,
+  targets: ReadonlyMap<string, ExecutionTarget>,
+  log: (line: string) => void,
+): Promise<boolean> {
+  try {
+    const fleet = await store.loadFleet();
+
+    const listed = new Set(fleet.map((entry) => entry.hostKey ?? entry.sessionID));
+
+    await binder.reconcileBindings(
+      (target) => targets.get(target)?.provider?.brokerAuth ?? null,
+      listed,
+      log,
+    );
+  } catch (error) {
+    log(
+      `atc could not settle runtime auth bindings (${error instanceof Error ? error.message : String(error)})`,
+    );
+
+    return false;
+  }
+
+  return true;
+}
+
 interface ConfirmToken {
   readonly session: SessionID;
   readonly expiresAt: number;

package/src/daemon/execution-provider.ts

@@ -1,3 +1,6 @@
+import type { DaemonError } from '../protocol/daemon-error';
+import type { BrokerAuthHost } from './broker-auth-host';
+
 /**
  * The host a session's harness runs on: it starts a process in a
  * pseudo-terminal and, as its capabilities declare, unpacks files into its
@@ -22,6 +25,11 @@ export interface ExecutionProvider {
   // host has none. Absent on the daemon's own machine.
   readonly guest?: GuestLayout;
 
+  // How a harness here can take its credential from impd's broker instead
+  // of holding it. Absent on a host with no broker, which never starts a
+  // session that needs one.
+  readonly brokerAuth?: BrokerAuthHost;
+
   // Readies the host a harness is about to start on: a remote host is
   // created when missing, woken when asleep, and held awake while its
   // harnesses run. Rejects with the refusal before any harness starts.
@@ -41,8 +49,12 @@ export interface ExecutionProvider {
 
   // Puts a host to sleep with every harness on it kept inside, so a revive
   // finds each one as it was. Rejects with `host_leased` when another owner
-  // keeps the host awake, and leaves the host as it was then.
-  readonly suspendHost: (host: string) => Promise<void>;
+  // keeps the host awake, and leaves the host as it was then. A sleep runs
+  // after any readying of the host before it, and a readying waits for it.
+  // isIdle makes it a sleep of an idle host only: it is checked when the
+  // sleep starts and again just before the host sleeps, and a host that a
+  // harness or a readying keeps busy stays awake with `host_unavailable`.
+  readonly suspendHost: (host: string, isIdle?: () => boolean) => Promise<void>;
 
   // Deletes a host and everything on it, harnesses included. Nothing brings
   // a destroyed host back.
@@ -65,6 +77,10 @@ export interface HostRequest {
   // Whether the harness about to start needs atc inside the host, which a
   // provider that ships its own binary installs when missing.
   readonly installATC?: boolean;
+
+  // Whether the daemon has nothing running or starting on the host, which
+  // the provider checks before it gives the host's lease back on its own.
+  readonly isIdle?: () => boolean;
 }
 
 export interface GuestLayout {
@@ -132,6 +148,20 @@ export interface HarnessSpec {
   readonly cols: number;
   readonly rows: number;
 
+  // Whether the harness must not start unless the host's credential broker
+  // is ready: the host refuses the start and runs nothing otherwise, on
+  // every start, a revive's included.
+  readonly requireBroker?: boolean;
+
+  // Admits each start or attach of a harness that requires the broker by
+  // calling send, which hands the request to the host, or rejects with the
+  // refusal that ends the harness instead, sending nothing. send gets the
+  // admission's ticket.
+  readonly admit?: (
+    kind: 'start' | 'attach',
+    send: (ticket: LaunchTicket) => void,
+  ) => Promise<void>;
+
   // Takes each connection a process of the harness opens to the daemon. A
   // remote provider relays them from a socket inside the host that serves
   // this harness alone, and points the harness's ATC_SOCKET at it.
@@ -143,6 +173,18 @@ export interface HarnessSpec {
  * lines: each line the process writes arrives whole, and each line the
  * daemon writes reaches the process in order.
  */
+/**
+ * One admitted request of a harness behind the broker. check runs just
+ * before the request goes out and returns the refusal that stops it
+ * unsent, or null to let it go; release gives the admission up once its
+ * connection ends without the request going out. Each runs at most once
+ * to any effect.
+ */
+export interface LaunchTicket {
+  readonly check: () => DaemonError | null;
+  readonly release: () => void;
+}
+
 export interface HarnessRelay {
   readonly onLine: (listener: (line: string) => void) => void;
   readonly onClose: (listener: () => void) => void;
@@ -176,6 +218,12 @@ export interface HarnessHandle {
   // a provider that can send one; absent on a provider that cannot.
   readonly killForced?: () => void;
 
+  // Resolves once the harness's process has started, or a running one was
+  // attached, and rejects with the refusal when the host ends the harness
+  // or the daemon lets go of it first. Absent on a provider whose harness
+  // starts at once.
+  readonly waitForStart?: () => Promise<void>;
+
   // Resolves true once the harness's process has exited, and false when the
   // wait runs out first or the harness stops being followed without an
   // exit, such as a host that went to sleep with the process inside.