@zgeoff/atc 2.42.0 → 3.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgeoff/atc",
-  "version": "2.42.0",
+  "version": "3.1.0",
   "description": "Terminal control tower for coding-agent sessions",
   "homepage": "https://github.com/zgeoff/atc#readme",
   "bugs": "https://github.com/zgeoff/atc/issues",
@@ -45,7 +45,7 @@
     "@modelcontextprotocol/sdk": "1.31.0",
     "@xterm/addon-serialize": "0.14.0",
     "@xterm/headless": "6.0.0",
-    "@zgeoff/imp-client": "0.27.0",
+    "@zgeoff/imp-client": "0.39.0",
     "better-auth": "1.7.6",
     "bun-pty": "0.4.10",
     "citty": "0.2.2",

package/src/agents/agent-adapter.ts

@@ -43,9 +43,11 @@ export interface SpawnPlan {
  * host, null when the host has none, and the folder the session's own
  * 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, and
- * the variables its auth profiles set.
+ * launches under, which keys any settings the agent writes for it, the
+ * placeholder variables the harness holds in place of a credential, the
+ * variables its auth profiles set, and, when the binding holds a secret of
+ * kind `oauth`, the sign-in state impd lists for each such secret, keyed by
+ * the secret's name.
  */
 export interface GuestPaths {
   readonly atc: string | null;
@@ -54,9 +56,20 @@ export interface GuestPaths {
     readonly revision: number;
     readonly env: Readonly<Record<string, string>>;
     readonly profileEnv: Readonly<Record<string, string>>;
+    readonly oauth?: Readonly<Record<string, GuestOAuthState>>;
   };
 }
 
+/**
+ * Where the sign-in of an `oauth` secret stands in impd: `ready` while impd
+ * holds an access token for it, and the payload of its last ID token,
+ * identifiers and never a credential, or null before impd has one.
+ */
+export interface GuestOAuthState {
+  readonly status: 'pending' | 'ready' | 'needs_login';
+  readonly idClaims: Readonly<Record<string, unknown>> | null;
+}
+
 /**
  * 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

package/src/agents/build-agent-adapters.ts

@@ -16,7 +16,7 @@ export function buildAgentAdapters(
 ): AgentAdapter[] {
   return config.agents.map((entry): AgentAdapter => {
     if (entry.kind === 'codex') {
-      return new CodexAdapter(entry);
+      return new CodexAdapter(entry, config);
     }
 
     if (entry.kind === 'grok') {

package/src/agents/build-codex-auth-file.ts

@@ -0,0 +1,62 @@
+/**
+ * The `auth.json` a Codex session on a remote host signs in with, which
+ * holds no credential: impd's broker sets the real access token on each
+ * request to chatgpt.com. Codex reads a ChatGPT sign-in from it with no
+ * sign-in step when the access token is opaque, so it never refreshes the
+ * token at start, and the last refresh lies far ahead, so it never
+ * refreshes on age. The ID token carries the email and the OpenAI auth
+ * claims of impd's ID token and nothing else, under an unsigned header,
+ * since Codex reads its claims and never checks a signature. The account
+ * id must be the real one: Codex sends it with every request and checks
+ * it against the account's workspaces before each session.
+ */
+export function buildCodexAuthFile(
+  idClaims: Readonly<Record<string, unknown>>,
+  accountID: string,
+): string {
+  const auth = {
+    auth_mode: 'chatgpt',
+    OPENAI_API_KEY: null,
+    tokens: {
+      id_token: buildUnsignedIDToken(idClaims),
+      access_token: PLACEHOLDER,
+      refresh_token: PLACEHOLDER,
+      account_id: accountID,
+    },
+    last_refresh: LAST_REFRESH,
+  };
+
+  return `${JSON.stringify(auth, null, 2)}\n`;
+}
+
+// The value impd's broker replaces with the access token on the host's side.
+const PLACEHOLDER = 'imp-broker-placeholder';
+
+// A last refresh Codex never counts as stale.
+const LAST_REFRESH = '2099-01-01T00:00:00Z';
+
+// The claims of impd's ID token that Codex reads: the account's email and
+// the object that holds its plan and account ids.
+const KEPT_CLAIMS = ['email', 'https://api.openai.com/auth'] as const;
+
+// A JWT of three base64url segments whose header says it is unsigned and
+// whose signature segment holds the placeholder, since Codex needs three
+// non-empty segments.
+function buildUnsignedIDToken(idClaims: Readonly<Record<string, unknown>>): string {
+  const payload = Object.fromEntries(
+    KEPT_CLAIMS.filter((claim) => idClaims[claim] !== undefined).map((claim) => [
+      claim,
+      idClaims[claim],
+    ]),
+  );
+
+  return [
+    toBase64URL(JSON.stringify({ alg: 'none', typ: 'JWT' })),
+    toBase64URL(JSON.stringify(payload)),
+    toBase64URL(PLACEHOLDER),
+  ].join('.');
+}
+
+function toBase64URL(text: string): string {
+  return Buffer.from(text, 'utf8').toString('base64url');
+}

package/src/agents/build-codex-config.ts

@@ -0,0 +1,10 @@
+/**
+ * The `config.toml` of a Codex session on a remote host: credentials stay
+ * in the `auth.json` atc writes, never in a keyring, and the TUI checks
+ * for no update, since the host's image fixes the version it runs.
+ */
+export function buildCodexConfig(): string {
+  return ['cli_auth_credentials_store = "file"', 'check_for_update_on_startup = false', ''].join(
+    '\n',
+  );
+}

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

@@ -0,0 +1,53 @@
+import type { SpawnPlan } from './agent-adapter';
+import { CODEX_TRUST_SEED_FILE } from './codex-trust-seed-file';
+
+/**
+ * The launch of a Codex CLI that runs in a remote host with a Codex home of
+ * the session's own inside its guest folder, so no sign-in or setting of
+ * the host's image reaches it. The folder persists for the session, so a
+ * resume finds the sessions Codex recorded there. Before each run a shell
+ * copies in the sign-in file, the config, and the hook file staged under
+ * `authDir`, a folder of the guest folder, appends the clone trust seed to
+ * that config when the guest folder holds one, and unsets every variable
+ * that would sign Codex in another way. `argv` is the CLI's own command
+ * line.
+ */
+export function buildCodexGuestLaunch(
+  guestDir: string,
+  authDir: string,
+  argv: readonly string[],
+): SpawnPlan & { readonly env: { readonly CODEX_HOME: string } } {
+  const codexHome = `${guestDir}/${CODEX_HOME_FOLDER}`;
+
+  return {
+    bin: 'sh',
+    args: [
+      '-c',
+      SEED_HOME_SCRIPT,
+      'sh',
+      codexHome,
+      `${guestDir}/${authDir}`,
+      `${guestDir}/${CODEX_TRUST_SEED_FILE}`,
+      ...argv,
+    ],
+    env: { CODEX_HOME: codexHome },
+  };
+}
+
+const CODEX_HOME_FOLDER = 'codex-home';
+
+// Variables Codex takes a credential from ahead of its sign-in file.
+const CREDENTIAL_VARIABLES = ['OPENAI_API_KEY', 'CODEX_API_KEY', 'CODEX_ACCESS_TOKEN'];
+
+// The arguments are the Codex home, the staged folder, the trust seed, and
+// the CLI's own command line. The home and its sign-in file are its
+// owner's alone; the CLI itself starts under the host's own umask.
+const SEED_HOME_SCRIPT = [
+  '( umask 077 && mkdir -p "$1" && cp "$2/auth.json" "$1/auth.json" )',
+  'cp "$2/config.toml" "$1/config.toml"',
+  '{ [ ! -f "$3" ] || cat "$3" >> "$1/config.toml"; }',
+  'cp "$2/hooks.json" "$1/hooks.json"',
+  'shift 3',
+  `unset ${CREDENTIAL_VARIABLES.join(' ')}`,
+  'exec "$@"',
+].join(' && ');

package/src/agents/build-codex-hook-file.ts

@@ -0,0 +1,23 @@
+import { buildCLIArgv } from './build-cli-argv';
+import { buildCLICommand } from './build-cli-command';
+
+const CODEX_HOOK_EVENTS = [
+  'SessionStart',
+  'UserPromptSubmit',
+  'PermissionRequest',
+  'Stop',
+] as const;
+
+/**
+ * The Codex hook file whose entries report each hook event to atc under
+ * the codex agent, run through `argv`: the atc of the daemon's machine by
+ * default, or the atc inside a remote host.
+ */
+export function buildCodexHookFile(argv: readonly string[] = buildCLIArgv()): string {
+  const cmd = buildCLICommand('hook-report --agent codex', argv);
+  const buildEntry = (timeout: number) => [{ hooks: [{ type: 'command', command: cmd, timeout }] }];
+  const hooks = Object.fromEntries(CODEX_HOOK_EVENTS.map((event) => [event, buildEntry(5)]));
+
+  // Codex caps SessionEnd hooks at three seconds.
+  return `${JSON.stringify({ hooks: { ...hooks, SessionEnd: buildEntry(3) } }, null, 2)}\n`;
+}

package/src/agents/build-codex-trust-seed.ts

@@ -0,0 +1,13 @@
+import { CODEX_TRUST_SEED_FILE } from './codex-trust-seed-file';
+
+/**
+ * The guest file that trusts the exact root of a verified clone in a Codex
+ * session's own config: a `projects` table the launch appends to the
+ * session's `config.toml`. A JSON string is a valid TOML basic string, so
+ * the root is quoted as one.
+ */
+export function buildCodexTrustSeed(root: string): Readonly<Record<string, string>> {
+  return {
+    [CODEX_TRUST_SEED_FILE]: `\n[projects.${JSON.stringify(root)}]\ntrust_level = "trusted"\n`,
+  };
+}

package/src/agents/codex-adapter.ts

@@ -2,18 +2,25 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 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 { AgentID } from '../shared/agent-id';
 import type { AgentSessionID } from '../shared/agent-session-id';
 import { buildOptionalString } from '../shared/build-optional-string';
 import type { AgentEntry } from '../shared/collect-agents';
+import type { Config } from '../shared/config';
 import { isRecord } from '../shared/report';
+import { resolveAuthProfiles } from '../shared/resolve-auth-profiles';
 import { toAgentSessionID } from '../shared/to-agent-session-id';
 import { toShellArg } from '../shared/to-shell-arg';
 import { truncateDetail } from '../shared/truncate-detail';
 import type {
   AgentAdapter,
   AgentProfile,
+  AuthSelection,
+  GuestOAuthState,
+  GuestPaths,
+  GuestSpawnPlan,
   NameUpdate,
   ResumeCheck,
   SpawnOptionSpecs,
@@ -21,6 +28,11 @@ import type {
   SpawnPlan,
 } from './agent-adapter';
 import { buildArgsWithoutFlags } from './build-args-without-flags';
+import { buildCodexAuthFile } from './build-codex-auth-file';
+import { buildCodexConfig } from './build-codex-config';
+import { buildCodexGuestLaunch } from './build-codex-guest-launch';
+import { buildCodexHookFile } from './build-codex-hook-file';
+import { buildCodexTrustSeed } from './build-codex-trust-seed';
 import { findFlagValue } from './find-flag-value';
 import { planPastedLineInput } from './plan-pasted-line-input';
 import { resolveAgentHome } from './resolve-agent-home';
@@ -46,6 +58,8 @@ const CODEX_MODEL_FLAGS = ['-m', '--model'];
  * semantics, and session_index.jsonl name-pulling. Hooks are a user-installed
  * entry in the Codex hook config (`atc codex-hooks` prints it) that the user
  * trusts once in the Codex TUI; atc never writes into the user's Codex config.
+ * An entry with `auth` signs in on an imp through the ChatGPT sign-in impd's
+ * broker holds, with a Codex home of the session's own that atc writes.
  */
 export class CodexAdapter implements AgentAdapter {
   readonly id: AgentID;
@@ -68,12 +82,24 @@ export class CodexAdapter implements AgentAdapter {
   // line is pasted and then submitted.
   readonly planLineInput = planPastedLineInput;
 
+  // Present only for an entry with `auth`: any other entry runs on a
+  // remote host as a local spawn plans it, under the sign-in of the host's
+  // image, and needs no atc there.
+  readonly planGuestSpawn?: (opts: SpawnOptions, guest: GuestPaths) => GuestSpawnPlan | null;
+
   private readonly entry: AgentEntry;
 
-  constructor(entry: AgentEntry) {
+  private readonly authProfiles: Config['authProfiles'];
+
+  constructor(entry: AgentEntry, config?: Pick<Config, 'authProfiles'>) {
     this.entry = entry;
+    this.authProfiles = config?.authProfiles ?? new Map();
     this.id = entry.id;
 
+    if (entry.auth !== undefined) {
+      this.planGuestSpawn = (opts, guest) => this.planSignedInGuestSpawn(opts, guest);
+    }
+
     this.profile = {
       label: entry.label,
       kind: 'codex',
@@ -102,6 +128,131 @@ export class CodexAdapter implements AgentAdapter {
     };
   }
 
+  // With `auth` configured, Codex signs in with the ChatGPT sign-in 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.entry.auth;
+
+    if (auth === undefined) {
+      return null;
+    }
+
+    return {
+      gateway: { id: this.id, baseURL: CHATGPT_CODEX_URL, auth },
+      profiles: this.authProfiles,
+      brokerRequired: false,
+    };
+  }
+
+  // A remote session without the broker runs as a local spawn plans it,
+  // under the sign-in of the host's image. One behind the broker reports
+  // through the atc inside its host, so without one it cannot run there,
+  // and it runs with a Codex home of its own: a sign-in file that holds
+  // no credential, a config, and the hook file, staged per binding
+  // revision. Its hooks are trusted at launch, since atc wrote them.
+  private planSignedInGuestSpawn(opts: SpawnOptions, guest: GuestPaths): GuestSpawnPlan | null {
+    if (guest.auth === undefined) {
+      return { ...this.planSpawn(opts), files: {} };
+    }
+
+    if (guest.atc === null) {
+      return null;
+    }
+
+    const authDir = `auth-r${guest.auth.revision}`;
+    const signIn = this.requireSignIn(guest.auth.oauth ?? {});
+    const plan = this.planSpawn(opts);
+
+    // the flag outranks a trusted clone's own config, which could move the
+    // sign-in out of the file atc writes
+    const launch = buildCodexGuestLaunch(guest.dir, authDir, [
+      plan.bin,
+      HOOK_TRUST_FLAG,
+      '-c',
+      FILE_CREDENTIALS_OVERRIDE,
+      ...plan.args,
+    ]);
+
+    return {
+      bin: launch.bin,
+      args: launch.args,
+      files: {
+        [`${authDir}/auth.json`]: buildCodexAuthFile(signIn.idClaims, signIn.accountID),
+        [`${authDir}/config.toml`]: buildCodexConfig(),
+        [`${authDir}/hooks.json`]: buildCodexHookFile([guest.atc]),
+      },
+      env: { ...guest.auth.profileEnv, ...guest.auth.env, ...launch.env },
+    };
+  }
+
+  // Seeds the config 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.entry.auth === undefined) {
+      return null;
+    }
+
+    return buildCodexTrustSeed(root);
+  }
+
+  // The ID token claims and account id of the oauth secret this entry's
+  // profiles send to chatgpt.com, or the refusal for a sign-in that is not
+  // ready or that holds no account id.
+  private requireSignIn(states: Readonly<Record<string, GuestOAuthState>>): {
+    readonly idClaims: Readonly<Record<string, unknown>>;
+    readonly accountID: string;
+  } {
+    const secret = this.findChatGPTSecret();
+    const state = secret === null ? undefined : states[secret];
+    const name = secret ?? 'the oauth secret';
+    const renew = `sign Codex in again and run imp secret add ${name} --kind oauth ... --replace with the new refresh token`;
+
+    if (state?.status !== 'ready') {
+      throw new DaemonError(
+        'auth_signin_needed',
+        `agent '${this.id}' signs in through ${name}, whose sign-in in impd is ${state?.status ?? 'not listed'}; ${renew}`,
+        { agent: this.id, secret, status: state?.status ?? null },
+      );
+    }
+
+    const auth = state.idClaims?.[OPENAI_AUTH_CLAIM];
+    const accountID = isRecord(auth) ? auth['chatgpt_account_id'] : undefined;
+
+    if (state.idClaims === null || typeof accountID !== 'string' || accountID === '') {
+      throw new DaemonError(
+        'auth_signin_needed',
+        `agent '${this.id}' signs in through ${name}, whose ID token in impd holds no ChatGPT account id; ${renew}`,
+        { agent: this.id, secret, status: state.status },
+      );
+    }
+
+    return { idClaims: state.idClaims, accountID };
+  }
+
+  // The secret this entry's profiles send to chatgpt.com, or null when
+  // they no longer resolve to one.
+  private findChatGPTSecret(): string | null {
+    const auth = this.entry.auth;
+
+    if (auth === undefined) {
+      return null;
+    }
+
+    const resolution = resolveAuthProfiles(this.authProfiles, auth.profiles);
+
+    if ('problem' in resolution) {
+      return null;
+    }
+
+    const found = resolution.resolved.secrets.find((secret) =>
+      secret.rules.some((rule) => rule.host === CHATGPT_HOST),
+    );
+
+    return found?.secret ?? null;
+  }
+
   normalizeHook(e: HookEvent): AdapterEvent {
     const parsed = CODEX_HOOK_PAYLOAD_SCHEMA.safeParse(e.payload);
     const payload: CodexHookPayload = parsed.success ? parsed.data : {};
@@ -222,6 +373,21 @@ export class CodexAdapter implements AgentAdapter {
   }
 }
 
+// Where Codex sends its ChatGPT sign-in: the endpoint its model requests go
+// to, and the host impd's broker sets the access token on.
+const CHATGPT_CODEX_URL = 'https://chatgpt.com/backend-api/codex';
+const CHATGPT_HOST = 'chatgpt.com';
+
+// The ID token claim that holds the ChatGPT account and plan.
+const OPENAI_AUTH_CLAIM = 'https://api.openai.com/auth';
+
+// Codex's documented flag that runs hooks without the trust a person
+// gives them in the TUI, meant for automation that vets its hook sources.
+const HOOK_TRUST_FLAG = '--dangerously-bypass-hook-trust';
+
+// A config override on the command line, which outranks every config file.
+const FILE_CREDENTIALS_OVERRIDE = 'cli_auth_credentials_store="file"';
+
 // What a Codex spawn can override. Codex documents its reasoning effort as
 // whatever the selected model advertises, with no closed list of levels, so
 // atc takes no effort for it.

package/src/agents/codex-trust-seed-file.ts

@@ -0,0 +1,4 @@
+/**
+ * The guest-relative file that holds a Codex session's clone trust.
+ */
+export const CODEX_TRUST_SEED_FILE = 'codex-trust.toml';

package/src/agents/print-codex-hook-file.ts

@@ -1,26 +1,11 @@
-import { buildCLICommand } from './build-cli-command';
-
-const CODEX_HOOK_EVENTS = [
-  'SessionStart',
-  'UserPromptSubmit',
-  'PermissionRequest',
-  'Stop',
-] as const;
+import { buildCodexHookFile } from './build-codex-hook-file';
 
 /**
  * Print the Codex hook entries to stdout. The operator merges them into
  * `$CODEX_HOME/hooks.json` and trusts them once in the Codex TUI — Codex
- * parses untrusted hooks but never runs them. atc never writes that path.
+ * parses untrusted hooks but never runs them. atc never writes the user's
+ * own Codex config.
  */
 export function printCodexHookFile(): void {
   process.stdout.write(buildCodexHookFile());
 }
-
-function buildCodexHookFile(): string {
-  const cmd = buildCLICommand('hook-report --agent codex');
-  const buildEntry = (timeout: number) => [{ hooks: [{ type: 'command', command: cmd, timeout }] }];
-  const hooks = Object.fromEntries(CODEX_HOOK_EVENTS.map((event) => [event, buildEntry(5)]));
-
-  // Codex caps SessionEnd hooks at three seconds.
-  return `${JSON.stringify({ hooks: { ...hooks, SessionEnd: buildEntry(3) } }, null, 2)}\n`;
-}

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

@@ -3,7 +3,7 @@
  * may not clean up after one:
  *
  * - `auth_impd_too_old`: impd lacks grantable tokens, secret rebinds or
- *   exec requirements.
+ *   exec requirements, or oauth secrets for a binding that holds one.
  * - `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/imp-client-port.ts

@@ -65,6 +65,7 @@ export class ImpClientPort implements ImpPort {
       grantableTokens: features?.['grantableTokens'] === true,
       secretRebind: features?.['secretRebind'] === true,
       execRequire: features?.['execRequire'] === true,
+      oauthSecrets: features?.['oauthSecrets'] === true,
     };
   };
 
@@ -84,17 +85,7 @@ export class ImpClientPort implements ImpPort {
   readonly readSecrets = async (): Promise<readonly ImpSecret[]> => {
     const secrets = await this.tryCall((client) => client.secrets.list());
 
-    return secrets.map((secret) => ({
-      name: secret.name,
-      kind: secret.kind,
-      rules: secret.rules.map((rule) => ({
-        host: rule.host,
-        header: rule.header,
-        scheme: rule.scheme,
-        ...(rule.user === undefined ? {} : { user: rule.user }),
-      })),
-      imps: [...secret.imps],
-    }));
+    return secrets.map((secret) => toImpSecret(secret));
   };
 
   readonly readGrants = async (name: string): Promise<readonly string[]> => {
@@ -327,6 +318,32 @@ export class ImpClientPort implements ImpPort {
   }
 }
 
+// A secret as the client lists it.
+type ClientSecret = Awaited<ReturnType<ImpClient['secrets']['list']>>[number];
+
+// A secret in the port's terms, with an oauth secret's sign-in status and
+// ID token claims and none of its other state.
+// oxlint-disable-next-line prefer-readonly-parameter-types -- a secret's dates have no readonly form
+function toImpSecret(secret: ClientSecret): ImpSecret {
+  const listed: ImpSecret = {
+    name: secret.name,
+    kind: secret.kind,
+    rules: secret.rules.map((rule) => ({
+      host: rule.host,
+      header: rule.header,
+      scheme: rule.scheme,
+      ...(rule.user === undefined ? {} : { user: rule.user }),
+    })),
+    imps: [...secret.imps],
+  };
+
+  const oauth = secret.oauth;
+
+  return oauth === undefined
+    ? listed
+    : { ...listed, oauth: { status: oauth.status, idClaims: oauth.idClaims } };
+}
+
 // A lease as the client returns it.
 interface ClientLease {
   readonly name: string;

package/src/daemon/imp-port.ts

@@ -84,6 +84,10 @@ export interface ImpFeatures {
   // A start may list what must be ready before the command runs, and impd
   // refuses the start without running it when one is not.
   readonly execRequire: boolean;
+
+  // impd holds secrets of kind `oauth`, whose access token it renews from a
+  // refresh token.
+  readonly oauthSecrets: boolean;
 }
 
 /**
@@ -96,7 +100,7 @@ export type ImpExecRequirement = 'broker';
 type ImpScope = 'read' | 'exec' | 'manage';
 
 export interface ImpIdentity {
-  readonly kind: 'token' | 'ssh' | 'tailnet' | 'dashboard';
+  readonly kind: 'token' | 'ssh' | 'tailnet' | 'dashboard' | 'oauth';
   readonly name: string;
   readonly scope: ImpScope;
 
@@ -111,11 +115,26 @@ export interface ImpIdentity {
 
 export interface ImpSecret {
   readonly name: string;
-  readonly kind: 'anthropic' | 'custom' | 'github' | 'npm';
+  readonly kind: 'anthropic' | 'custom' | 'github' | 'npm' | 'oauth';
   readonly rules: readonly ImpSecretRule[];
 
   // The imps holding a grant of the secret.
   readonly imps: readonly string[];
+
+  // The sign-in state of an `oauth` secret; absent for any other kind.
+  readonly oauth?: ImpOAuthState;
+}
+
+/**
+ * Where an `oauth` secret's sign-in stands: `ready` while impd holds an
+ * access token, `pending` until a refresh first works, and `needs_login`
+ * once the token endpoint refused the refresh token for good. `idClaims`
+ * holds the payload of the last ID token, identifiers and never a
+ * credential, or null before impd has one.
+ */
+interface ImpOAuthState {
+  readonly status: 'pending' | 'ready' | 'needs_login';
+  readonly idClaims: Readonly<Record<string, unknown>> | null;
 }
 
 // How impd adds a secret to requests for one host.

package/src/daemon/load-oauth-states.ts

@@ -0,0 +1,67 @@
+import type { GuestOAuthState } from '../agents/agent-adapter';
+import { DaemonError } from '../protocol/daemon-error';
+import type { BrokerAuthHost } from './broker-auth-host';
+import type { AuthBinding } from './build-auth-binding';
+import { collectSecretRuleMismatches } from './collect-secret-rule-mismatches';
+import { ImpPortError } from './imp-port-error';
+
+/**
+ * The sign-in state impd lists for each secret a binding holds as kind
+ * `oauth`, keyed by the secret's name, or undefined for a binding that
+ * holds none, which reads nothing from impd. It reads impd's features and
+ * then its secrets once, and refuses an impd without oauth secrets, and a
+ * bound oauth secret that impd lacks or holds with another kind or rules,
+ * with the codes the binding's own gate would give.
+ */
+export async function loadOAuthStates(
+  host: BrokerAuthHost,
+  binding: AuthBinding,
+): Promise<Readonly<Record<string, GuestOAuthState>> | undefined> {
+  const expected = binding.secrets.filter((secret) => secret.kind === 'oauth');
+
+  if (expected.length === 0) {
+    return undefined;
+  }
+
+  try {
+    const features = await host.port.readFeatures();
+
+    if (!features.oauthSecrets) {
+      throw new DaemonError(
+        'auth_impd_too_old',
+        `impd lacks oauth secret support, which ${expected.map((secret) => secret.secret).join(', ')} needs`,
+        { oauthSecrets: false, secrets: expected.map((secret) => secret.secret) },
+      );
+    }
+
+    const held = await host.port.readSecrets();
+
+    const mismatches = collectSecretRuleMismatches(expected, held);
+
+    if (mismatches.length > 0) {
+      throw new DaemonError(
+        'auth_secret_mismatch',
+        `impd holds ${mismatches.map((mismatch) => `${mismatch.secret} (${mismatch.reason})`).join(', ')} unlike the binding`,
+        { mismatches },
+      );
+    }
+
+    return Object.fromEntries(
+      held.flatMap((secret) =>
+        secret.oauth !== undefined && expected.some((want) => want.secret === secret.name)
+          ? [[secret.name, { status: secret.oauth.status, idClaims: secret.oauth.idClaims }]]
+          : [],
+      ),
+    );
+  } catch (error) {
+    if (error instanceof ImpPortError) {
+      throw new DaemonError(
+        'host_unavailable',
+        `impd refused a runtime auth call: ${error.message}`,
+        { provider: 'imp', problem: error.code.toLowerCase() },
+      );
+    }
+
+    throw error;
+  }
+}

package/src/daemon/runtime-auth-binder.ts

@@ -955,7 +955,15 @@ async function verifyGate(
 ): Promise<void> {
   const secrets = binding.secrets.map((secret) => secret.secret);
 
-  await verifyBrokerAuthority(host.port, { impNames: [impName], secrets }, host.impPrefix);
+  const oauthSecrets = binding.secrets
+    .filter((secret) => secret.kind === 'oauth')
+    .map((secret) => secret.secret);
+
+  await verifyBrokerAuthority(
+    host.port,
+    { impNames: [impName], secrets, oauthSecrets },
+    host.impPrefix,
+  );
 
   const held = await host.port.readSecrets();
 

package/src/daemon/sessions.ts

@@ -46,6 +46,7 @@ import type {
 } from './execution-provider';
 import { findExecutionRefusal } from './find-execution-refusal';
 import type { BridgeBinding } from './is-binding-current';
+import { loadOAuthStates } from './load-oauth-states';
 import { LocalPTYProvider } from './local-pty-provider';
 import { mintSessionID } from './mint-session-id';
 import { pickSessionState } from './pick-session-state';
@@ -982,7 +983,7 @@ export class SessionManager {
       if (!isLocalTrust && !isGuestTrust) {
         throw new DaemonError(
           'unsupported',
-          'trustClonedWorkspace requires stock Claude on the local target, or stock Claude or a Claude gateway signed in through the broker on an imp target',
+          'trustClonedWorkspace requires stock Claude on the local target, or stock Claude, a Claude gateway, or Codex signed in through the broker on an imp target',
         );
       }
     }
@@ -2014,7 +2015,7 @@ export class SessionManager {
         : {
             atc: guest.atc,
             dir,
-            auth: await this.planGuestAuth(hostKey, auth.mode, auth.binding),
+            auth: await this.planGuestAuth(hostKey, auth),
           };
 
     const plan =
@@ -2096,18 +2097,22 @@ export class SessionManager {
 
   // The binding revision and placeholders a guest plan behind the broker
   // launches under: the next host's first revision, or the revision the
-  // shared host holds.
+  // shared host holds, with the sign-in state impd lists for each oauth
+  // secret the binding holds.
   private async planGuestAuth(
     hostKey: SessionID,
-    mode: HarnessAuthSetup['mode'],
-    binding: Pick<AuthBinding, 'placeholderEnv' | 'profileEnv'>,
+    auth: HarnessAuthSetup,
   ): Promise<NonNullable<GuestPaths['auth']>> {
-    const held = mode === 'create' ? null : await this.requireAuthBinder().findBinding(hostKey);
+    const held =
+      auth.mode === 'create' ? null : await this.requireAuthBinder().findBinding(hostKey);
+
+    const oauth = await loadOAuthStates(auth.host, auth.binding);
 
     return {
       revision: held?.revision ?? 1,
-      env: binding.placeholderEnv,
-      profileEnv: binding.profileEnv,
+      env: auth.binding.placeholderEnv,
+      profileEnv: auth.binding.profileEnv,
+      ...(oauth === undefined ? {} : { oauth }),
     };
   }
 

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

@@ -4,12 +4,13 @@ import { verifyTokenImpAuthority } from './verify-token-imp-authority';
 
 /**
  * What a provisioning call is about to touch: the imps under their actual
- * names, as the target's runtime namespace builds them, and every secret
- * the binding grants them.
+ * names, as the target's runtime namespace builds them, every secret the
+ * binding grants them, and those of the secrets it binds as kind `oauth`.
  */
 export interface BrokerActivation {
   readonly impNames: readonly string[];
   readonly secrets: readonly string[];
+  readonly oauthSecrets?: readonly string[];
 }
 
 /**
@@ -17,7 +18,8 @@ export interface BrokerActivation {
  * impd's features, then the token's identity, and writes nothing, so a
  * refusal leaves impd as it was. It rejects unless impd has grantable
  * tokens, secret rebinds and exec requirements, so a start can refuse to
- * run without a ready broker, the token may manage each imp and reaches no
+ * run without a ready broker, and oauth secrets when the binding holds one,
+ * the token may manage each imp and reaches no
  * imp outside the namespace whose imp names start with the prefix, and the
  * token may grant every bound secret.
  * Whether each secret's rules match the binding is a separate comparison.
@@ -41,6 +43,16 @@ export async function verifyBrokerAuthority(
     );
   }
 
+  const oauthSecrets = activation.oauthSecrets ?? [];
+
+  if (oauthSecrets.length > 0 && !features.oauthSecrets) {
+    throw new BrokerAuthorityError(
+      'auth_impd_too_old',
+      `impd lacks oauth secret support, which ${oauthSecrets.join(', ')} needs`,
+      { oauthSecrets: features.oauthSecrets, secrets: oauthSecrets },
+    );
+  }
+
   const identity = await port.readIdentity();
 
   verifyTokenImpAuthority(identity, activation.impNames, impPrefix);

package/src/protocol/protocol.ts

@@ -51,6 +51,7 @@ const ERROR_CODES = [
   'auth_not_configured',
   'auth_target_unsupported',
   'auth_impd_too_old',
+  'auth_signin_needed',
   'auth_token_scope',
   'auth_token_too_broad',
   'auth_imp_out_of_scope',

package/src/shared/collect-agents.ts

@@ -4,6 +4,7 @@ import type { GatewayAuth } from './check-gateway-auth';
 import type { AuthProfile } from './collect-auth-profiles';
 import { collectClaudeAuth } from './collect-claude-auth';
 import type { ClaudeMCPServer } from './collect-claude-auth';
+import { collectCodexAuth } from './collect-codex-auth';
 import { collectProfileEnvProblems } from './collect-profile-env-problems';
 import { isSubscriptionOverrideVariable } from './is-subscription-override-variable';
 import { isRecord } from './report';
@@ -20,7 +21,8 @@ type AgentKind = 'claude' | 'codex' | 'grok';
  * environment, and the backend and credential it runs against. A Claude entry
  * with a `baseURL` is a gateway; without one it is stock Claude, whose
  * `auth` holds profiles alone, for the subscription sign-in, and whose
- * `mcpServers` reach their hosts through those profiles.
+ * `mcpServers` reach their hosts through those profiles. A Codex entry's
+ * `auth` holds profiles alone too, for its ChatGPT sign-in.
  */
 export interface AgentEntry {
   readonly id: AgentID;
@@ -83,9 +85,21 @@ function isAgentKind(value: unknown): value is AgentKind {
   return KINDS.some((kind) => kind === value);
 }
 
-// The fields every kind takes, and the ones only a Claude entry takes.
+// The fields every kind takes, and the ones each kind takes beside them.
 const COMMON_FIELDS = new Set(['kind', 'label', 'mark', 'bin', 'args']);
-const CLAUDE_FIELDS = new Set(['settings', 'env', 'baseURL', 'apiKeyHelper', 'auth']);
+
+const KIND_FIELDS: Readonly<Record<AgentKind, ReadonlySet<string>>> = {
+  claude: new Set(['settings', 'env', 'baseURL', 'apiKeyHelper', 'auth']),
+  codex: new Set(['auth']),
+  grok: new Set(),
+};
+
+const KNOWN_FIELDS: ReadonlySet<string> = new Set([
+  ...COMMON_FIELDS,
+  ...KIND_FIELDS.claude,
+  ...KIND_FIELDS.codex,
+  ...KIND_FIELDS.grok,
+]);
 
 const DEFAULT_LABELS: Readonly<Record<AgentKind, string>> = {
   claude: 'Claude',
@@ -124,6 +138,10 @@ function parseAgentEntry(
 
   const entry = buildEntry(id, found.kind, raw);
 
+  if (found.kind === 'codex') {
+    return readCodexAuth(entry, raw['auth'], authProfiles);
+  }
+
   if (found.kind !== 'claude') {
     return { entry };
   }
@@ -168,13 +186,13 @@ function collectFieldProblems(raw: Readonly<Record<string, unknown>>, kind: Agen
   const problems: string[] = [];
 
   for (const [name, value] of Object.entries(raw)) {
-    if (CLAUDE_FIELDS.has(name) && kind !== 'claude') {
-      problems.push(`${name} is not valid for kind ${kind}`);
+    if (!KNOWN_FIELDS.has(name)) {
+      problems.push(`unknown field ${name}`);
       continue;
     }
 
-    if (!COMMON_FIELDS.has(name) && !CLAUDE_FIELDS.has(name)) {
-      problems.push(`unknown field ${name}`);
+    if (!COMMON_FIELDS.has(name) && !KIND_FIELDS[kind].has(name)) {
+      problems.push(`${name} is not valid for kind ${kind}`);
       continue;
     }
 
@@ -262,6 +280,27 @@ function buildDefaultLabel(id: string, kind: AgentKind): string {
   return id === kind ? DEFAULT_LABELS[kind] : id;
 }
 
+// A Codex entry with the `auth` it holds, or every problem with that auth.
+// Codex takes no placeholder variable: atc writes the sign-in file the CLI
+// reads in place of a credential.
+function readCodexAuth(
+  entry: AgentEntry,
+  raw: unknown,
+  authProfiles: ReadonlyMap<string, AuthProfile>,
+): ParsedEntry {
+  if (raw === undefined) {
+    return { entry };
+  }
+
+  const collected = collectCodexAuth(raw, authProfiles);
+
+  if (collected.profiles === null) {
+    return { problems: [...collected.errors] };
+  }
+
+  return { entry: { ...entry, auth: { profiles: collected.profiles, placeholderEnv: {} } } };
+}
+
 interface ReadClaudeAuth {
   readonly auth?: GatewayAuth;
   readonly mcpServers?: readonly ClaudeMCPServer[];

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

@@ -6,15 +6,17 @@ import { isRecord } from './report';
  * A named reference to a credential impd holds: the secret's name, never
  * its value, and the profiles a session selecting this one needs beside
  * it. A `custom` profile holds the one rule impd applies when a request
- * reaches its host, always a bearer header. A `github` profile holds no
- * rule: impd's `github` kind fixes its hosts and headers.
+ * reaches its host, always a bearer header. An `oauth` profile holds the
+ * same rule for a secret whose access token impd renews from a refresh
+ * token. A `github` profile holds no rule: impd's `github` kind fixes its
+ * hosts and headers.
  */
 export type AuthProfile = CustomAuthProfile | GitHubAuthProfile;
 
 interface CustomAuthProfile {
   readonly name: string;
   readonly secret: string;
-  readonly kind: 'custom';
+  readonly kind: 'custom' | 'oauth';
   readonly host: string;
   readonly header: string;
   readonly scheme: 'bearer';
@@ -94,8 +96,8 @@ function parseAuthProfile(name: string, entry: unknown): AuthProfile | string {
   const dependencies = entry['dependencies'];
   const kind = entry['kind'] ?? 'custom';
 
-  if (kind !== 'custom' && kind !== 'github') {
-    return 'kind must be custom or github, the kinds atc binds';
+  if (kind !== 'custom' && kind !== 'oauth' && kind !== 'github') {
+    return 'kind must be custom, oauth, or github, the kinds atc binds';
   }
 
   if (typeof secret !== 'string' || !SECRET_NAME.test(secret)) {
@@ -148,7 +150,7 @@ function parseAuthProfile(name: string, entry: unknown): AuthProfile | string {
   return {
     name,
     secret,
-    kind: 'custom',
+    kind,
     host,
     header,
     scheme,
@@ -162,7 +164,7 @@ function parseAuthProfile(name: string, entry: unknown): AuthProfile | string {
 // other value, so a credential is never written into a profile.
 const ENV_PLACEHOLDER = 'imp-broker-placeholder';
 const ENV_NAME = /^[A-Z_][A-Z0-9_]*$/;
-const RESERVED_ENV_PREFIXES = ['ANTHROPIC_', 'CLAUDE_', 'ATC_'];
+const RESERVED_ENV_PREFIXES = ['ANTHROPIC_', 'CLAUDE_', 'ATC_', 'CODEX_', 'OPENAI_'];
 
 const RESERVED_ENV_NAMES: ReadonlySet<string> = new Set(['PATH', 'HOME']);
 

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

@@ -0,0 +1,70 @@
+import type { AuthProfile } from './collect-auth-profiles';
+import { isRecord } from './report';
+import { resolveAuthProfiles } from './resolve-auth-profiles';
+
+interface CollectedCodexAuth {
+  readonly profiles: readonly string[] | null;
+  readonly errors: readonly string[];
+}
+
+/**
+ * Reads the `auth` of a Codex entry against the auth profiles: the
+ * profiles a Codex session on a target that reaches impd's broker signs in
+ * through. One of them must send an `oauth` secret to `chatgpt.com` as a
+ * bearer authorization header, where Codex sends its ChatGPT sign-in, and
+ * the rest bind beside it, such as a GitHub token. An entry that does not
+ * resolve or holds no such profile gets null and every problem with it.
+ */
+export function collectCodexAuth(
+  raw: unknown,
+  authProfiles: ReadonlyMap<string, AuthProfile>,
+): CollectedCodexAuth {
+  const profiles = isRecord(raw) ? raw['profiles'] : undefined;
+
+  if (
+    !isRecord(raw) ||
+    !Array.isArray(profiles) ||
+    profiles.length === 0 ||
+    !profiles.every((name) => typeof name === 'string')
+  ) {
+    return { profiles: null, errors: ['auth must be an object with a non-empty profiles array'] };
+  }
+
+  const extra = Object.keys(raw).find((key) => key !== 'profiles');
+
+  if (extra !== undefined) {
+    return {
+      profiles: null,
+      errors: [
+        `auth.${extra} cannot be set: atc fixes the endpoint and the sign-in of a Codex session`,
+      ],
+    };
+  }
+
+  const selected = profiles.map(String);
+  const resolution = resolveAuthProfiles(authProfiles, selected);
+
+  if ('problem' in resolution) {
+    return { profiles: null, errors: [`auth: ${resolution.problem.message}`] };
+  }
+
+  const secret = resolution.resolved.secrets.find((s) =>
+    s.rules.some((rule) => rule.host === CHATGPT_HOST),
+  );
+
+  const rule = secret?.rules.find((r) => r.host === CHATGPT_HOST);
+
+  if (secret?.kind !== 'oauth' || rule?.header !== 'authorization' || rule.scheme !== 'bearer') {
+    return {
+      profiles: null,
+      errors: [
+        `auth needs an oauth profile that sets a bearer authorization header for ${CHATGPT_HOST}, where Codex sends its ChatGPT sign-in`,
+      ],
+    };
+  }
+
+  return { profiles: selected, errors: [] };
+}
+
+// The one host Codex sends its ChatGPT sign-in to.
+const CHATGPT_HOST = 'chatgpt.com';