@zgeoff/atc 2.32.0 → 2.32.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgeoff/atc",
-  "version": "2.32.0",
+  "version": "2.32.1",
   "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

@@ -52,11 +52,14 @@ export interface GuestPaths {
 /**
  * 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.
+ * selection resolves against. `brokerRequired` is true for an agent that
+ * starts only behind the broker; false lets it start on a target that
+ * reaches no broker under the sign-in that target's host holds.
  */
 export interface AuthSelection {
   readonly gateway: Pick<GatewayConfig, 'id' | 'baseURL'> & { readonly auth: GatewayAuth };
   readonly profiles: ReadonlyMap<string, AuthProfile>;
+  readonly brokerRequired: boolean;
 }
 
 /**

package/src/agents/build-claude-config-seed.ts

@@ -0,0 +1,23 @@
+import { CLAUDE_CONFIG_SEED_FILE } from './claude-config-seed-file';
+
+/**
+ * The guest file that seeds a session's own Claude config folder with the
+ * state the CLI reads from `.claude.json` to start without its first-run
+ * onboarding, and with folder trust for `trustedRoot`, the exact root of a
+ * verified clone, when one is given. It holds no account: the placeholder
+ * credential is what keeps the CLI from asking for a login. Without a
+ * trusted root the CLI asks a person to trust the workspace on its first
+ * start.
+ */
+export function buildClaudeConfigSeed(
+  trustedRoot: string | null,
+): Readonly<Record<string, string>> {
+  const seed =
+    trustedRoot === null
+      ? ONBOARDED_CONFIG
+      : { ...ONBOARDED_CONFIG, projects: { [trustedRoot]: { hasTrustDialogAccepted: true } } };
+
+  return { [CLAUDE_CONFIG_SEED_FILE]: JSON.stringify(seed, null, 2) };
+}
+
+const ONBOARDED_CONFIG = { hasCompletedOnboarding: true };

package/src/agents/build-claude-guest-launch.ts

@@ -0,0 +1,55 @@
+import type { SpawnPlan } from './agent-adapter';
+import { CLAUDE_CONFIG_SEED_FILE } from './claude-config-seed-file';
+
+/**
+ * The launch of a Claude CLI that runs in a remote host with a config
+ * folder of the session's own inside its guest folder, so no account or
+ * setting of the host's image reaches it. A shell copies the seed into the
+ * folder only when the folder holds no `.claude.json` yet, then runs the
+ * CLI, so a resumed session keeps the state the CLI wrote, a folder trust
+ * a person accepted included. `argv` is the CLI's own command line. The
+ * shell exits before it runs the CLI when the host's environment sets any
+ * of `refusedEnv`, which must be variable names, and says which one.
+ */
+export function buildClaudeGuestLaunch(
+  guestDir: string,
+  argv: readonly string[],
+  refusedEnv: readonly string[] = [],
+): SpawnPlan & { readonly env: Readonly<Record<string, string>> } {
+  const configDir = `${guestDir}/${CLAUDE_CONFIG_FOLDER}`;
+  const guards = refusedEnv.map((name) => buildEnvGuard(name)).join('');
+
+  return {
+    bin: 'sh',
+    args: [
+      '-c',
+      `${guards}${SEED_CONFIG_SCRIPT}`,
+      'sh',
+      configDir,
+      `${guestDir}/${CLAUDE_CONFIG_SEED_FILE}`,
+      ...argv,
+    ],
+    env: { CLAUDE_CONFIG_DIR: configDir },
+  };
+}
+
+const ENV_NAME = /^[A-Z_][A-Z0-9_]*$/u;
+
+// A shell step that stops the launch when the variable is set, empty or
+// not, with a line that says which variable and why.
+function buildEnvGuard(name: string): string {
+  if (!ENV_NAME.test(name)) {
+    throw new Error(`refused variable ${name} is not an environment variable name`);
+  }
+
+  return `[ -z "\${${name}+x}" ] || { echo "atc: ${name} is set in this host's environment and overrides the sign-in atc gives this session, so Claude does not start" >&2; exit ${REFUSED_EXIT}; }; `;
+}
+
+// sysexits' EX_CONFIG: a configuration error.
+const REFUSED_EXIT = 78;
+const CLAUDE_CONFIG_FOLDER = 'claude-config';
+
+// The arguments are the config folder, the seed, and the CLI's own command
+// line.
+const SEED_CONFIG_SCRIPT =
+  'mkdir -p "$1" && { [ -e "$1/.claude.json" ] || cp "$2" "$1/.claude.json"; } && shift 2 && exec "$@"';

package/src/agents/claude-adapter.ts

@@ -1,10 +1,12 @@
 import { existsSync } from 'node:fs';
 import { z } from 'zod';
 import type { AdapterEvent } from '../protocol/adapter-event';
+import { DaemonError } from '../protocol/daemon-error';
 import type { HookEvent } from '../protocol/hook-event';
 import type { AgentSessionID } from '../shared/agent-session-id';
 import { buildOptionalString } from '../shared/build-optional-string';
 import type { Config } from '../shared/config';
+import { isBrokerVariable } from '../shared/is-broker-variable';
 import { isRecord } from '../shared/report';
 import { toAgentSessionID } from '../shared/to-agent-session-id';
 import { toShellArg } from '../shared/to-shell-arg';
@@ -12,6 +14,7 @@ import { truncateDetail } from '../shared/truncate-detail';
 import type {
   AgentAdapter,
   AgentProfile,
+  AuthSelection,
   GuestPaths,
   GuestSpawnPlan,
   HeadlessRunner,
@@ -21,7 +24,10 @@ import type {
   SpawnOptions,
   SpawnPlan,
 } from './agent-adapter';
+import { buildArgsWithoutFlags } from './build-args-without-flags';
 import { buildATCBridgeFiles } from './build-atc-bridge-files';
+import { buildClaudeConfigSeed } from './build-claude-config-seed';
+import { buildClaudeGuestLaunch } from './build-claude-guest-launch';
 import { buildClaudeOverrideArgs } from './build-claude-override-args';
 import { buildHookSettings } from './build-hook-settings';
 import { CLAUDE_EFFORT_LEVELS } from './claude-effort-levels';
@@ -109,13 +115,36 @@ export class ClaudeAdapter implements AgentAdapter {
 
     return {
       bin: this.config.claudeBin,
-      args: this.buildArgs(opts, this.settingsFile, this.writeBridge()),
+      args: this.buildArgs(this.config.claudeArgs, opts, this.settingsFile, this.writeBridge()),
+    };
+  }
+
+  // With `claudeAuth` configured, Claude signs in with the subscription
+  // token impd's broker holds on a target that reaches the broker, and
+  // with the sign-in of the host it runs on anywhere else.
+  findAuthSelection(): AuthSelection | null {
+    const auth = this.config.claudeAuth;
+
+    if (auth === null) {
+      return null;
+    }
+
+    return {
+      gateway: {
+        id: this.id,
+        baseURL: ANTHROPIC_API_URL,
+        auth: { profiles: auth.profiles, placeholderEnv: { [OAUTH_VARIABLE]: PLACEHOLDER } },
+      },
+      profiles: this.config.authProfiles,
+      brokerRequired: false,
     };
   }
 
   // A remote session reports through the atc inside its host, so without
   // one it has no instrumentation and cannot run there. Its settings and
-  // its copy of the mod travel with it, and it has no statusline.
+  // its copy of the mod travel with it, and it has no statusline. A
+  // session that signs in through impd's broker runs with a config folder
+  // of its own and the placeholder in place of the token.
   planGuestSpawn(opts: SpawnOptions, guest: GuestPaths): GuestSpawnPlan | null {
     if (guest.atc === null) {
       return null;
@@ -127,9 +156,18 @@ export class ClaudeAdapter implements AgentAdapter {
       ([path, content]): [string, string] => [`atc-bridge/${path}`, content],
     );
 
+    if (guest.auth !== undefined) {
+      return this.planSubscriptionGuestSpawn(opts, guest.dir, guest.auth, argv, bridge);
+    }
+
     return {
       bin: this.config.claudeBin,
-      args: this.buildArgs(opts, `${guest.dir}/settings.json`, `${guest.dir}/atc-bridge`),
+      args: this.buildArgs(
+        this.config.claudeArgs,
+        opts,
+        `${guest.dir}/settings.json`,
+        `${guest.dir}/atc-bridge`,
+      ),
       files: {
         'settings.json': JSON.stringify(buildHookSettings({ id: this.id }, 0, argv), null, 2),
         ...Object.fromEntries(bridge),
@@ -137,9 +175,114 @@ export class ClaudeAdapter implements AgentAdapter {
     };
   }
 
-  private buildArgs(opts: SpawnOptions, settings: string, pluginDir: string): string[] {
+  // Seeds the config folder of a session that signs in through impd's
+  // broker with trust for the clone; any other remote session reads the
+  // config of the host's image, which atc never writes.
+  planGuestWorkspaceTrust(root: string): Readonly<Record<string, string>> | null {
+    if (this.config.claudeAuth === null) {
+      return null;
+    }
+
+    return buildClaudeConfigSeed(root);
+  }
+
+  // A settings file of the session's own per binding revision carries the
+  // placeholder, and so does the CLI's environment. The configured
+  // arguments go without a permission mode, so the mode the session's own
+  // user settings set applies. A credential, endpoint, or provider variable
+  // in the configured settings, or in the host's environment, would keep
+  // the CLI from sending the placeholder, so either refuses the start.
+  private planSubscriptionGuestSpawn(
+    opts: SpawnOptions,
+    dir: string,
+    auth: NonNullable<GuestPaths['auth']>,
+    argv: readonly string[],
+    bridge: readonly (readonly [string, string])[],
+  ): GuestSpawnPlan {
+    const refusal = this.findCredentialOverride();
+
+    if (refusal !== null) {
+      throw refusal;
+    }
+
+    const settingsPath = `auth-r${auth.revision}/settings.json`;
+
+    const settings = buildHookSettings(
+      { id: this.id, env: { ...auth.env, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: '1' } },
+      0,
+      argv,
+    );
+
+    const launch = buildClaudeGuestLaunch(
+      dir,
+      [
+        this.config.claudeBin,
+        ...this.buildArgs(
+          buildArgsWithoutFlags(this.config.claudeArgs, ['--permission-mode']),
+          opts,
+          `${dir}/${settingsPath}`,
+          `${dir}/atc-bridge`,
+        ),
+      ],
+      [...OUTRANKING_VARIABLES],
+    );
+
+    return {
+      bin: launch.bin,
+      args: launch.args,
+      files: {
+        [settingsPath]: JSON.stringify(settings, null, 2),
+        ...buildClaudeConfigSeed(null),
+        ...Object.fromEntries(bridge),
+      },
+      env: { ...launch.env, ...auth.env },
+    };
+  }
+
+  // The refusal for configured arguments whose inline `--settings` sets a
+  // variable that overrides the subscription sign-in or routes the CLI
+  // around impd's broker, or null when they set none.
+  private findCredentialOverride(): DaemonError | null {
+    const inline = findFlagValue(this.config.claudeArgs, ['--settings']);
+
+    if (inline === null) {
+      return null;
+    }
+
+    let parsed: unknown;
+
+    try {
+      parsed = JSON.parse(inline);
+    } catch {
+      return null;
+    }
+
+    const env = isRecord(parsed) ? parsed['env'] : undefined;
+    const keys = isRecord(env) ? Object.keys(env) : [];
+
+    const variable = keys.find(
+      (key) => OUTRANKING_VARIABLES.has(key) || key === OAUTH_VARIABLE || isBrokerVariable(key),
+    );
+
+    if (variable === undefined) {
+      return null;
+    }
+
+    return new DaemonError(
+      'auth_target_unsupported',
+      `claude signs in through impd's broker on this target, but claudeArgs set ${variable} in --settings, which would override or route around that sign-in`,
+      { agent: this.id, problem: 'guest_env_conflict', variable },
+    );
+  }
+
+  private buildArgs(
+    configured: readonly string[],
+    opts: SpawnOptions,
+    settings: string,
+    pluginDir: string,
+  ): string[] {
     return [
-      ...buildClaudeOverrideArgs(this.config.claudeArgs, opts),
+      ...buildClaudeOverrideArgs(configured, opts),
       '--settings',
       settings,
       '--plugin-dir',
@@ -298,6 +441,29 @@ export class ClaudeAdapter implements AgentAdapter {
   }
 }
 
+// The endpoint Claude Code sends a subscription token to, the variable it
+// reads that token from, and the value impd's broker replaces with the
+// token on the host's side.
+const ANTHROPIC_API_URL = 'https://api.anthropic.com';
+const OAUTH_VARIABLE = 'CLAUDE_CODE_OAUTH_TOKEN';
+const PLACEHOLDER = 'imp-broker-placeholder';
+
+// The variables that keep Claude Code from sending the subscription token
+// to the Anthropic API: a credential it takes ahead of that token, another
+// endpoint, or a cloud provider it signs in to instead.
+const OUTRANKING_VARIABLES: ReadonlySet<string> = new Set([
+  'ANTHROPIC_AUTH_TOKEN',
+  'ANTHROPIC_API_KEY',
+  'ANTHROPIC_BASE_URL',
+  'CLAUDE_CODE_USE_BEDROCK',
+  'CLAUDE_CODE_USE_VERTEX',
+  'CLAUDE_CODE_USE_FOUNDRY',
+  'CLAUDE_CODE_USE_MANTLE',
+  'CLAUDE_CODE_USE_ANTHROPIC_AWS',
+  'CLAUDE_CODE_USE_ANTHROPIC_GOOGLE_CLOUD',
+  'CLAUDE_CODE_USE_GATEWAY',
+]);
+
 // The aliases Claude Code documents for `--model`, each resolving to a model
 // the account picks. A full model name is accepted as well.
 const CLAUDE_MODEL_ALIASES = [

package/src/agents/claude-config-seed-file.ts

@@ -0,0 +1,6 @@
+/**
+ * Where the seed of a session's own Claude config folder travels inside its
+ * guest folder: beside the config folder rather than in it, so a transfer
+ * never replaces the state an earlier run of the CLI left there.
+ */
+export const CLAUDE_CONFIG_SEED_FILE = 'claude-config-seed.json';

package/src/agents/gateway-adapter.ts

@@ -23,6 +23,8 @@ import type {
   SpawnPlan,
 } from './agent-adapter';
 import { buildATCBridgeFiles } from './build-atc-bridge-files';
+import { buildClaudeConfigSeed } from './build-claude-config-seed';
+import { buildClaudeGuestLaunch } from './build-claude-guest-launch';
 import { buildClaudeOverrideArgs } from './build-claude-override-args';
 import { buildHookSettings } from './build-hook-settings';
 import { buildRestoreModeArgs } from './build-restore-mode-args';
@@ -141,6 +143,7 @@ export class GatewayAdapter implements AgentAdapter {
     return {
       gateway: { id: this.gateway.id, baseURL: this.gateway.baseURL, auth },
       profiles: this.config.authProfiles,
+      brokerRequired: true,
     };
   }
 
@@ -214,30 +217,25 @@ export class GatewayAdapter implements AgentAdapter {
       argv,
     );
 
-    const configDir = `${guest.dir}/${CLAUDE_CONFIG_FOLDER}`;
+    const launch = buildClaudeGuestLaunch(guest.dir, [
+      this.gateway.bin,
+      ...this.buildArgs(
+        opts,
+        this.buildGuestModeArgs(),
+        `${guest.dir}/${settingsPath}`,
+        `${guest.dir}/atc-bridge`,
+      ),
+    ]);
 
     return {
-      bin: 'sh',
-      args: [
-        '-c',
-        SEED_CONFIG_SCRIPT,
-        'sh',
-        configDir,
-        `${guest.dir}/${CONFIG_SEED_FILE}`,
-        this.gateway.bin,
-        ...this.buildArgs(
-          opts,
-          this.buildGuestModeArgs(),
-          `${guest.dir}/${settingsPath}`,
-          `${guest.dir}/atc-bridge`,
-        ),
-      ],
+      bin: launch.bin,
+      args: launch.args,
       files: {
         [settingsPath]: JSON.stringify(settings, null, 2),
-        [CONFIG_SEED_FILE]: JSON.stringify(ONBOARDED_CONFIG, null, 2),
+        ...buildClaudeConfigSeed(null),
         ...Object.fromEntries(bridge),
       },
-      env: { CLAUDE_CONFIG_DIR: configDir, ...guest.auth.env },
+      env: { ...launch.env, ...guest.auth.env },
     };
   }
 
@@ -246,16 +244,7 @@ export class GatewayAdapter implements AgentAdapter {
       return null;
     }
 
-    return {
-      [CONFIG_SEED_FILE]: JSON.stringify(
-        {
-          ...ONBOARDED_CONFIG,
-          projects: { [root]: { hasTrustDialogAccepted: true } },
-        },
-        null,
-        2,
-      ),
-    };
+    return buildClaudeConfigSeed(root);
   }
 
   normalizeHook(e: HookEvent): AdapterEvent {
@@ -434,27 +423,6 @@ const PLACEHOLDER = 'imp-broker-placeholder';
 // The Claude CLI's mode that asks a person before each action.
 const MANUAL_PERMISSION_MODE = 'default';
 
-// The Claude config folder a brokered session gets inside its guest
-// folder, so no account or setting of the host's image reaches it.
-const CLAUDE_CONFIG_FOLDER = 'claude-config';
-
-// The state the Claude CLI reads from its config folder's `.claude.json`
-// to start without its first-run onboarding. It holds no account: the
-// placeholder credential is what keeps the CLI from asking for a login.
-// It holds no folder trust either, so the CLI asks a person to trust the
-// workspace on its first start.
-const ONBOARDED_CONFIG = { hasCompletedOnboarding: true };
-
-// Where that state travels, beside the config folder rather than in it.
-const CONFIG_SEED_FILE = 'claude-config-seed.json';
-
-// Copies the seed into the config folder only when the folder holds no
-// `.claude.json` yet, then runs the CLI. A resumed session keeps the state
-// the CLI wrote, a folder trust a person accepted included. The arguments
-// are the config folder, the seed, and the CLI's own command line.
-const SEED_CONFIG_SCRIPT =
-  'mkdir -p "$1" && { [ -e "$1/.claude.json" ] || cp "$2" "$1/.claude.json"; } && shift 2 && exec "$@"';
-
 // The gateway's settings without a credential helper, which a brokered
 // session never runs.
 function buildSettingsWithoutHelper(

package/src/cli.ts

@@ -62,6 +62,12 @@ const main = defineCommand({
             description:
               'Origin clients reach the --http server at, such as https://mcp.example.com',
           },
+          'wait-for-daemon': {
+            type: 'boolean',
+            default: false,
+            description:
+              'With --http, wait for a running daemon instead of starting one, for a managed daemon',
+          },
         },
         async run(ctx) {
           if (!ctx.args.http) {
@@ -85,6 +91,7 @@ const main = defineCommand({
             host: ctx.args.host ?? null,
             port: port === null ? null : port.port,
             publicURL: ctx.args['public-url'] ?? null,
+            waitForDaemon: ctx.args['wait-for-daemon'],
           });
         },
       }),
@@ -382,6 +389,7 @@ async function runDaemon(listenArg: string | null, tokenFile: string | null): Pr
     ...cfg.principalErrors,
     ...cfg.workspaceErrors,
     ...cfg.authProfileErrors,
+    ...cfg.claudeAuthErrors,
     ...cfg.gatewayErrors,
   ]) {
     console.error(`atc daemon: config: ${problem}`);

package/src/client/boot-daemon.ts

@@ -37,11 +37,18 @@ export interface DaemonBootOptions {
   // session it hosts; without the callback, or resolving false, the boot
   // rejects and the daemon keeps running.
   readonly onProtocolMismatch?: (mismatch: ProtocolMismatch) => Promise<boolean>;
+
+  // When set, the boot never starts a daemon: it waits this many
+  // milliseconds for one to answer, then rejects. A caller that a service
+  // manager starts beside a managed daemon sets it, so the two never race
+  // for the state directory.
+  readonly waitForDaemonMs?: number;
 }
 
 /**
  * Opens a handshaken client to the daemon, booting the daemon first when
- * neither the computed socket nor the one in the daemon's record answers.
+ * neither the computed socket nor the one in the daemon's record answers,
+ * or waiting for one to answer when the caller set `waitForDaemonMs`.
  * Overlapping calls in one process share a single boot. A daemon from an
  * older build stays in service, since stopping it would end every hosted
  * session, and is reported as stale so the caller can offer a deliberate
@@ -53,15 +60,21 @@ export interface DaemonBootOptions {
  * its own boot would otherwise flag daemons that are already current.
  */
 export async function bootDaemonClient(options: DaemonBootOptions = {}): Promise<DaemonBoot> {
+  const wait =
+    options.waitForDaemonMs === undefined
+      ? null
+      : { deadline: Date.now() + options.waitForDaemonMs, timeoutMs: options.waitForDaemonMs };
+
   for (let attempt = 0; attempt < 2; attempt++) {
     const build = getBuild();
-
-    const opened = await openOrBootDaemon();
-
+    const opened = wait === null ? await openOrBootDaemon() : await waitForDaemon(wait);
     const client = opened.client;
 
     try {
-      const hello = await client.sendHello(build);
+      const hello =
+        wait === null
+          ? await client.sendHello(build)
+          : await waitForHello(() => client.sendHello(build), wait);
 
       return {
         client,
@@ -125,6 +138,59 @@ async function openOrBootDaemon(): Promise<OpenedDaemon> {
   return booted;
 }
 
+// The time a waiting boot gives up, and the length of its wait for the
+// error text.
+interface DaemonWait {
+  readonly deadline: number;
+  readonly timeoutMs: number;
+}
+
+/**
+ * Polls the known sockets until a daemon answers, and never starts one.
+ */
+async function waitForDaemon(wait: DaemonWait): Promise<OpenedDaemon> {
+  for (;;) {
+    const opened = await tryOpenKnownDaemon();
+
+    if (opened !== null) {
+      return opened;
+    }
+
+    if (Date.now() >= wait.deadline) {
+      throw new Error(formatWaitFailure(wait.timeoutMs));
+    }
+
+    await Bun.sleep(100);
+  }
+}
+
+/**
+ * Sends the handshake and rejects once the wait's deadline passes, so a
+ * daemon that takes the connection but never answers cannot hold the wait
+ * open.
+ */
+async function waitForHello(
+  sendHello: () => Promise<Readonly<Record<string, unknown>>>,
+  wait: DaemonWait,
+): Promise<Readonly<Record<string, unknown>>> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  const expired = new Promise<never>((_resolve, reject) => {
+    timer = setTimeout(
+      () => {
+        reject(new Error(formatWaitFailure(wait.timeoutMs)));
+      },
+      Math.max(0, wait.deadline - Date.now()),
+    );
+  });
+
+  try {
+    return await Promise.race([sendHello(), expired]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 /**
  * Tries the socket this environment computes, then the one the running
  * daemon recorded in the state directory: a client whose environment lacks
@@ -185,13 +251,28 @@ const bootDaemonOnce = makeSingleFlight(async () => {
 // directory a sandbox hides, needs a different fix than one that never
 // started, so the message tells them apart.
 function formatBootFailure(): string {
+  return (
+    formatUnreachableDaemon() ?? 'the atc daemon did not come up; try `atc daemon` for its output'
+  );
+}
+
+function formatUnreachableDaemon(): string | null {
   const record = findDaemonRecord(daemonRecordFile);
 
   if (record !== null && isProcessAlive(record.pid)) {
     return `the atc daemon (pid ${record.pid}) is running, but its socket ${record.socketPath} is unreachable from here`;
   }
 
-  return 'the atc daemon did not come up; try `atc daemon` for its output';
+  return null;
+}
+
+// A waiting caller was told not to start a daemon, so the message says so
+// and points at starting the managed one.
+function formatWaitFailure(timeoutMs: number): string {
+  return (
+    formatUnreachableDaemon() ??
+    `no atc daemon answered at ${daemonSocketPath} within ${timeoutMs / 1000}s, and this process does not start one; start \`atc daemon\` (or the service that runs it) first`
+  );
 }
 
 function isProcessAlive(pid: number): boolean {

package/src/client/spawn-picker.ts

@@ -1721,8 +1721,8 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
       return;
     }
 
-    // An agent that takes its credential from impd's broker runs only on a
-    // target that reaches the broker.
+    // An agent that starts only behind impd's broker runs only on a target
+    // that reaches the broker.
     const brokered = isBrokerAgent(listed['agents'], this.agent);
     const listedTargets = collectTargetPicks(listed);
     const picks = listedTargets.filter((t) => !brokered || t.brokerAuth);
@@ -2026,13 +2026,18 @@ function buildProbedRepo(
   };
 }
 
-// Whether the daemon lists an agent as taking its credential from impd's
-// broker; a daemon that does not say lists none.
+// Whether the daemon lists an agent as starting only behind impd's broker.
+// A daemon that sends no `brokerRequired` holds every agent with
+// `brokerAuth` to the broker, and one that sends neither 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,
+      (entry: unknown) =>
+        isRecord(entry) &&
+        entry['id'] === agent &&
+        entry['brokerAuth'] === true &&
+        entry['brokerRequired'] !== false,
     )
   );
 }

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

@@ -2,8 +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, and one that takes its credential from impd's broker only
-  // where some target reaches the broker.
+  // session, and one that starts only behind impd's broker only where some
+  // target reaches the broker.
   readonly spawn: boolean;
   readonly readTranscript: boolean;
 
@@ -22,9 +22,13 @@ 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`.
+  // Whether the agent takes its credential from impd's broker on a target
+  // whose entry has `brokerAuth`.
   readonly brokerAuth: boolean;
+
+  // Whether it starts only there. False for an agent that starts on any
+  // other target under the sign-in that target's host holds.
+  readonly brokerRequired: boolean;
   readonly capabilities: AgentCapabilities;
   readonly models: Readonly<Record<string, string>> | null;
   readonly spawnOptions: SpawnOptionEntries;
@@ -59,19 +63,21 @@ export function buildAgentList(
   return adapters.map((adapter) => {
     const profile = adapter.profile;
     const installed = profile === undefined ? false : isInstalled(profile.bin);
-    const brokerAuth = (adapter.findAuthSelection?.() ?? null) !== null;
+    const selection = adapter.findAuthSelection?.() ?? null;
+    const brokerRequired = selection?.brokerRequired ?? false;
 
     const spawnable =
       installed &&
       (adapter.findSpawnRefusal?.() ?? null) === null &&
-      (!brokerAuth || hasBrokerTarget);
+      (!brokerRequired || hasBrokerTarget);
 
     return {
       id: adapter.id,
       label: profile?.label ?? adapter.id,
       kind: profile?.kind ?? adapter.id,
       installed,
-      brokerAuth,
+      brokerAuth: selection !== null,
+      brokerRequired,
       capabilities: {
         spawn: spawnable,
         readTranscript: adapter.parseTranscriptLine !== undefined,

package/src/daemon/sessions.ts

@@ -599,19 +599,24 @@ export class SessionManager {
 
   /**
    * Throws the refusal for an agent that takes its credential from impd's
-   * broker on a target whose provider reaches no broker, before a spawn
-   * or an adopt does any work.
+   * broker on a target where it cannot, before a spawn or an adopt does
+   * any work: a target whose provider reaches no broker, for an agent that
+   * starts only behind one, or a broker the daemon cannot bind.
    */
   requireAgentTarget(agent: AgentID, target: string): void {
-    const adapter = this.findAdapter(agent);
+    const selection = this.findAdapter(agent)?.findAuthSelection?.() ?? null;
 
-    if (adapter === null || (adapter.findAuthSelection?.() ?? null) === null) {
+    if (selection === null) {
       return;
     }
 
-    const provider = this.targets.get(target)?.provider ?? null;
+    const host = this.targets.get(target)?.provider?.brokerAuth;
+
+    if (host === undefined && !selection.brokerRequired) {
+      return;
+    }
 
-    if (provider?.brokerAuth === undefined || this.authBinder === null) {
+    if (host === undefined || this.authBinder === null) {
       throw buildBrokerTargetRefusal(agent, target);
     }
   }
@@ -938,7 +943,7 @@ export class SessionManager {
       if (!isLocalTrust && !isGuestTrust) {
         throw new DaemonError(
           'unsupported',
-          'trustClonedWorkspace requires stock Claude on the local target or a brokered Claude gateway on an imp target',
+          'trustClonedWorkspace requires stock Claude on the local target, or stock Claude or a Claude gateway signed in through the broker on an imp target',
         );
       }
     }
@@ -1138,10 +1143,12 @@ export class SessionManager {
   }
 
   // What a harness of this agent needs to take its credential from impd's
-  // broker on a provider, or null when the agent takes none. Throws the
-  // refusal for a target whose provider has no broker, so no credential
-  // ever falls back to a local start, and for a selection the current auth
-  // profiles cannot bind.
+  // broker on a provider, or null when it takes none there: the agent
+  // takes none at all, or its selection lets it start on a target that
+  // reaches no broker under that host's own sign-in. Throws the refusal
+  // for an agent that starts only behind the broker on a target whose
+  // provider has none, so its credential never falls back to a local
+  // start, and for a selection the current auth profiles cannot bind.
   private resolveHarnessAuth(
     adapter: AgentAdapter,
     provider: ExecutionProvider,
@@ -1155,6 +1162,10 @@ export class SessionManager {
 
     const host = provider.brokerAuth;
 
+    if (host === undefined && !selection.brokerRequired) {
+      return null;
+    }
+
     if (host === undefined || this.authBinder === null) {
       throw buildBrokerTargetRefusal(adapter.id, target);
     }

package/src/mcp/mcp-tools.ts

@@ -61,7 +61,7 @@ const SPAWN_INPUT: Readonly<Record<string, unknown>> = z.toJSONSchema(
       "Where the session's working directory comes from. Omit it to run the session in cwd as it stands. With it, atc materializes a clean checkout into cwd on the target, which must not exist yet: {kind:'path', path, allowDirty?} checks out the pushed HEAD of a git checkout on the atc host, leaving its uncommitted and untracked changes behind with a warning, or refusing them when allowDirty is 'refuse'; {kind:'git', url, ref or sha, credentialRef?} checks out a branch, tag, or full commit of a repository, with credentialRef {kind:'env', name} naming the atc daemon's environment variable that holds its token. A directory outside git runs in place only on a target on the atc host itself (provider local-pty), with cwd equal to its path. Submodules and Git LFS are refused, and so is a URL that carries a credential.",
     ),
     trustClonedWorkspace: SPAWN_SCHEMA.shape.trustClonedWorkspace.describe(
-      "Trust the exact verified clone for this launch. An explicit true or false overrides the configured target trustClonedWorkspace default; omitting both keeps trust off. Requires a workspace source and either stock Claude on the local target, which adds trust for the clone root alone to the user's Claude config, or a brokered Claude gateway with isolated guest config on an imp target; other launches are refused. Accepts repository configuration and helpers without changing tool permission mode. Existing guest config is preserved.",
+      "Trust the exact verified clone for this launch. An explicit true or false overrides the configured target trustClonedWorkspace default; omitting both keeps trust off. Requires a workspace source and either stock Claude on the local target, which adds trust for the clone root alone to the user's Claude config, or, on an imp target, a brokered Claude gateway or stock Claude signed in through the broker, each with isolated guest config; other launches are refused. Accepts repository configuration and helpers without changing tool permission mode. Existing guest config is preserved.",
     ),
     detached: z
       .boolean()
@@ -223,6 +223,7 @@ const AGENTS_OUTPUT: Readonly<Record<string, unknown>> = {
           kind: { type: 'string' },
           installed: { type: 'boolean' },
           brokerAuth: { type: 'boolean' },
+          brokerRequired: { type: 'boolean' },
           capabilities: {
             type: 'object',
             properties: {

package/src/mcp-http-server.ts

@@ -12,17 +12,28 @@ interface MCPHTTPFlags {
   readonly host: string | null;
   readonly port: number | null;
   readonly publicURL: string | null;
+  readonly waitForDaemon: boolean;
 }
 
+// How long `--wait-for-daemon` waits before it exits. A service manager's
+// restart covers a daemon that takes longer.
+const DAEMON_WAIT_MS = 30_000;
+
 /**
- * Runs `atc mcp --http` in the foreground: boots the daemon when it is down
- * and serves MCP over HTTP until Ctrl-C. Approval codes print here, so the
+ * Runs `atc mcp --http` in the foreground: boots the daemon when it is down,
+ * or with `--wait-for-daemon` waits for one and exits when none answers, and
+ * serves MCP over HTTP until Ctrl-C. Approval codes print here, so the
  * terminal running it is where the operator approves a client.
  */
 export async function runMCPHTTPServer(build: string, flags: MCPHTTPFlags): Promise<void> {
   const config = loadMCPHTTPConfig();
+  const bootOptions = flags.waitForDaemon ? { waitForDaemonMs: DAEMON_WAIT_MS } : {};
+
+  const boot = await bootDaemonClient(bootOptions).catch((error: unknown) => {
+    console.error(`atc mcp --http: ${error instanceof Error ? error.message : String(error)}`);
 
-  const boot = await bootDaemonClient();
+    return process.exit(1);
+  });
 
   boot.client.stop();
 

package/src/shared/collect-claude-auth.ts

@@ -0,0 +1,84 @@
+import type { AuthProfile } from './collect-auth-profiles';
+import { isRecord } from './report';
+import { resolveAuthProfiles } from './resolve-auth-profiles';
+
+/**
+ * The profiles a stock Claude session on a target that reaches impd's
+ * broker signs in through: one of them sends the subscription's setup
+ * token to the Anthropic API as a bearer authorization header, and the
+ * rest bind beside it, such as a GitHub token.
+ */
+export interface ClaudeAuth {
+  readonly profiles: readonly string[];
+}
+
+interface CollectedClaudeAuth {
+  readonly auth: ClaudeAuth | null;
+  readonly errors: readonly string[];
+}
+
+/**
+ * Reads the `claudeAuth` entry against the auth profiles. An entry that
+ * does not resolve, or whose profiles send no bearer authorization header
+ * to the Anthropic API, is left out with every problem that refused it, so
+ * stock Claude keeps the sign-in of the host it runs on rather than binding
+ * a credential the CLI would never send.
+ */
+export function collectClaudeAuth(
+  raw: unknown,
+  authProfiles: ReadonlyMap<string, AuthProfile>,
+): CollectedClaudeAuth {
+  if (raw === undefined) {
+    return { auth: null, errors: [] };
+  }
+
+  const profiles = isRecord(raw) ? raw['profiles'] : undefined;
+
+  if (
+    !isRecord(raw) ||
+    !Array.isArray(profiles) ||
+    profiles.length === 0 ||
+    !profiles.every((name) => typeof name === 'string')
+  ) {
+    return {
+      auth: null,
+      errors: ['claudeAuth must be an object with a non-empty profiles array'],
+    };
+  }
+
+  const extra = Object.keys(raw).find((key) => key !== 'profiles');
+
+  if (extra !== undefined) {
+    return {
+      auth: null,
+      errors: [
+        `claudeAuth.${extra} cannot be set: atc fixes the endpoint and the placeholder of a Claude subscription session`,
+      ],
+    };
+  }
+
+  const selected = profiles.map(String);
+  const resolution = resolveAuthProfiles(authProfiles, selected);
+
+  if ('problem' in resolution) {
+    return { auth: null, errors: [`claudeAuth: ${resolution.problem.message}`] };
+  }
+
+  const rule = resolution.resolved.secrets
+    .flatMap((secret) => secret.rules)
+    .find((r) => r.host === ANTHROPIC_API_HOST);
+
+  if (rule?.header !== 'authorization' || rule.scheme !== 'bearer') {
+    return {
+      auth: null,
+      errors: [
+        `claudeAuth needs a profile that sets a bearer authorization header for ${ANTHROPIC_API_HOST}, where Claude Code sends its subscription token`,
+      ],
+    };
+  }
+
+  return { auth: { profiles: selected }, errors: [] };
+}
+
+// The one host Claude Code sends a subscription token to.
+const ANTHROPIC_API_HOST = 'api.anthropic.com';

package/src/shared/config.ts

@@ -5,6 +5,8 @@ import { buildOptionalString } from './build-optional-string';
 import { buildOptionalStringArray } from './build-optional-string-array';
 import { collectAuthProfiles } from './collect-auth-profiles';
 import type { AuthProfile } from './collect-auth-profiles';
+import { collectClaudeAuth } from './collect-claude-auth';
+import type { ClaudeAuth } from './collect-claude-auth';
 import { collectDirRoots } from './collect-dir-roots';
 import { collectGateways } from './collect-gateways';
 import type { GatewayConfig } from './collect-gateways';
@@ -23,6 +25,12 @@ import { resolveHomeDir } from './resolve-home-dir';
 export interface Config {
   claudeBin: string;
   claudeArgs: string[];
+
+  // The auth profiles stock Claude signs in through on a target that
+  // reaches impd's broker, null when it keeps the host's own sign-in there,
+  // and the problems that left an entry out.
+  claudeAuth: ClaudeAuth | null;
+  claudeAuthErrors: readonly string[];
   grokBin: string;
   grokArgs: string[];
   codexBin: string;
@@ -75,6 +83,8 @@ interface LeaderKey {
 const DEFAULTS: Config = {
   claudeBin: 'claude',
   claudeArgs: [],
+  claudeAuth: null,
+  claudeAuthErrors: [],
   grokBin: 'grok',
   grokArgs: [],
   codexBin: 'codex',
@@ -124,6 +134,7 @@ export const daemonRecordFile = join(stateDir, 'daemon.json');
 const CONFIG_SCHEMA = z.object({
   claudeBin: buildOptionalString(),
   claudeArgs: buildOptionalStringArray(),
+  claudeAuth: z.unknown().optional(),
   grokBin: buildOptionalString(),
   grokArgs: buildOptionalStringArray(),
   codexBin: buildOptionalString(),
@@ -225,6 +236,8 @@ function tryWriteDefaultConfig(file: string): void {
  */
 export function renderDefaultConfig(): string {
   const {
+    claudeAuth: _claudeAuth,
+    claudeAuthErrors: _claudeAuthErrors,
     gatewayErrors: _gatewayErrors,
     authProfiles: _authProfiles,
     authProfileErrors: _authProfileErrors,
@@ -284,6 +297,7 @@ export function parseConfig(raw: unknown, file: string = configFile): Config {
   const dirs = { roots: collectDirRoots(parsed.data.dirs) };
   const workspaces = collectWorkspacesConfig(parsed.data.workspaces);
   const authProfiles = collectAuthProfiles(parsed.data.authProfiles);
+  const claudeAuth = collectClaudeAuth(parsed.data.claudeAuth, authProfiles.profiles);
 
   const gateways = collectGateways(
     parsed.data.gateways,
@@ -302,6 +316,8 @@ export function parseConfig(raw: unknown, file: string = configFile): Config {
   return {
     claudeBin,
     claudeArgs,
+    claudeAuth: claudeAuth.auth,
+    claudeAuthErrors: claudeAuth.errors,
     grokBin,
     grokArgs,
     codexBin,